Visitar URL original
chore(tasks): add a shared component analysis report by poluru-labs · Pull Request #6986 · uswds/uswds · GitHub
Skip to content

chore(tasks): add a shared component analysis report - #6986

Open
poluru-labs wants to merge 6 commits into
uswds:developfrom
poluru-labs:docs/shared-components-list
Open

chore(tasks): add a shared component analysis report#6986
poluru-labs wants to merge 6 commits into
uswds:developfrom
poluru-labs:docs/shared-components-list

Conversation

@poluru-labs

@poluru-labs poluru-labs commented Sep 21, 2026

Copy link
Copy Markdown

Summary

Added npm run shared:components, which scans every directory under packages/ and writes a USWDS-styled HTML report to reports/shared-components.html. Maintainers can see which packages are reused, by whom, and through which Sass, JS, or Twig paths before changing a shared package.

Breaking change

This is not a breaking change.

Related issue

N/A

Related pull requests

None. This is a local analysis task and does not require a documentation-site update or changelog entry on uswds-site.

Preview link

Preview link:
Preview link: generate locally, then open the file
npm run shared:components open reports/shared-components.html
The HTML is written to reports/ and is gitignored, so there is no hosted demo on this PR.

Problem statement

Desired state: Maintainers can list every package under packages/ and see how those packages depend on and reuse one another — lines of source, UI-component uses, reused by, depends on, and used in — in one report.

Actual state: Package folders and Storybook show each component in isolation. They do not show Sass @forward, JS require/import, or Twig @components/ composition across the library.

Consequences: Changing a widely reused package (for example usa-icon, usa-input, or usa-button) has an unclear blast radius. Aggregators such as uswds and uswds-form-controls make it look as if every component is “shared,” which hides real UI-to-UI composition.

Solution

A Node task, tasks/shared-components.js, walks packages/, builds a dependency graph, and writes reports/shared-components.html.

What it does

  1. Lists each directory under packages/.
  2. Counts physical lines in .scss, .js, .twig, and .ts source (tests and Storybook stories are skipped).
  3. Records depends on from _index.scss @forward, JS require/import, and Twig include/embed/from/import of @components/….
  4. Inverts that graph for reused by / uses.
  5. Records used in from Twig files in other packages, including templates.

Why this approach

  • Matches other USWDS gulp/node tasks: run from package.json, log with doc-util.
  • Uses USWDS CSS/JS from the published CDN so the report does not need a local dist/ build.
  • Stores output in reports/ and gitignores that folder so generated HTML is not committed.

How it is implemented

  • Script: npm run shared:components → node tasks/shared-components.js
  • Output: reports/shared-components.html
  • Package kinds: UI component (usa-* / _usa-*), foundation, bundle, template
  • Uses / reused by count other UI components only. Aggregators (uswds, uswds-form-controls, uswds-typography, uswds-form-templates, uswds-validation, uswds-global, uswds-utilities) and the uswds-core JS registry are omitted so “included in the full library” is not counted as sharing.

Limitations

  • Reuse is only what the scanners find (Sass forwards, relative JS requires/imports, Twig @components/ includes). Dynamic or undocumented wiring is missed.
  • The report is a snapshot; re-run the task after package changes.
  • Generated HTML is local-only and not part of the npm package.

Major changes

  • Added tasks/shared-components.js to scan packages/ and generate the report.
  • Added "shared:components": "node tasks/shared-components.js" in package.json.
  • Added reports/ to .gitignore.
  • Report UI uses USWDS components and theme tokens (cards, summary box, table, tags, segmented buttons, skip nav, accordion). Search and filter buttons sit on one row.

AI disclosure

What AI tools did you use to create this MR?

  • No AI
  • Chat
  • Completions (e.g. Copilot)
  • Coding Agent

Author's checklist

  • Removed redundant AI comments (if applicable)
  • [ x] The changes on this PR are strictly limited to the ticket requirements (i.e., no scope creep)
  • [ x] I personally witnessed this code working in a local environment
  • [ x] Automated tests are passing
  • [ x] I have manually tested accessibility using physical devices and relevant assistive technology
    • [List the physical devices and assistive technology here]
  • I understand all the code and could debug it without AI 6 months from now

Testing and review

  1. From the repo root, run: npm run shared:components Confirm the log reports 25 shared UI components across 88 packages and Wrote reports/shared-components.html.
  2. Open reports/shared-components.html in a browser.

Feedback that would help: whether uses should stay UI-to-UI only, whether reports/ is the right output path, and whether this task should stay a standalone npm script or be wired into gulp.

@poluru-labs
docs(shared-componets-list): automate and geneate shared components l…
b1fb088 
…ist from packages folder and stored in reports folder
@github-actions

github-actions Bot commented Sep 21, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Hi @poluru-labs — thanks for your contribution!

There is one thing that may be holding this up: for security reasons, USWDS requires that all commits to this repo have a verified commit. The following commit(s) on this PR aren't verified:

  • b1fb088 — docs(shared-componets-list): automate and geneate shared components list from packages folder and stored in reports folder
  • 90d4990 — YOUR_COMMIT_MESSAGE

Here's what's needed:

  1. Set up signature verification in GitHub. Use one of the following GitHub guides to set up your verification signature:

  2. Rebase your commits with your verified signature. Once your signature is set up, complete the following steps in the terminal to update the verification status of your previous commits:

    git checkout docs/shared-components-list
git rebase origin/develop
git push --force-with-lease

Please let us know if you have any questions. We appreciate your help here. This comment will update automatically once your commits are verified.

@github-actions github-actions Bot added the Needs: Author Response 🔴 Waiting on a specific author action; also used by commit-signature automation. label Sep 21, 2026
@coderabbitai

coderabbitai Bot commented Sep 21, 2026 •
edited
Loading

Copy link
Copy Markdown

Review in Change Stack →

Important

Review skipped

Review was skipped as selected files did not have any reviewable changes.

⚙️ Run configuration
  • Configuration used: Repository: uswds/uswds/.coderabbit.yaml
  • Review profile: QUIET
  • Plan: Advanced
  • Run ID: 0cdd2360-0d30-4087-aa9b-d4ed77a32f9f
📥 Commits

Reviewing files that changed from the base of the PR and between f058523 and d651989.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Repository: uswds/uswds/.coderabbit.yaml

Review profile: QUIET

Plan: Advanced

Run ID: 0f55a891-9da4-4c22-acdc-3e98017fff50

📥 Commits

Reviewing files that changed from the base of the PR and between b1fb088 and 90d4990.

📒 Files selected for processing (1)
  • tasks/shared-components.js

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

📝 Summary

Summary by CodeRabbit

  • New Features

    • Added a shared-components report with searchable and filterable package information.
    • The report includes component reuse, source size, dependency relationships, Twig usage, and bundle coverage.
    • Added responsive layouts and expandable details for easier exploration.

  • Chores

    • Added a command to generate the shared-components report.
    • Generated report files are now excluded from version control.

The PR adds a shared-component scanner and HTML report. It exposes the scanner through npm run shared:components, ignores the generated report, and updates lockfile metadata, including the Sass package entry.

Changes: Shared component reporting

Layer / File(s) Summary
Scan and classify package sources
tasks/shared-components.js		 The script scans Sass, JavaScript, and Twig sources. It excludes configured directories and test or story files, counts files and lines, classifies packages, and records reuse and bundle relationships.
Build the HTML report
tasks/shared-components.js		 The script generates summary metrics, reuse tables, package details, filters, sorting, search controls, responsive styling, and counting rules.
Run and support report generation
package.json, tasks/shared-components.js, .gitignore, package-lock.json		 The npm script runs the generator. The generator writes reports/shared-components.html and logs results. The generated report is ignored. The lockfile updates peer metadata and replaces sass with sass-embedded.

Priority: ⚪ Not assessed

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Other

Suggested labels: Affects: Accessibility 🟡, Context: JavaScript, Affects: Compiling

Merge Risk: ⚪ Minimal · up to 90d49

This adds an opt-in local report generator without evidence of production behavior or data-integrity impact; it is mergeable with normal checks.

🚥 Pre-merge checks | ✅ 9 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Accessibility Verification Declared ⚠️ Warning The check applies because the new report adds ARIA attributes, tabindex, skip navigation, accordion buttons, filter-button state updates, and interactive filtering. The PR description does not name … Add a test matrix to the PR description. Name each assistive technology and browser combination used, and state what was verified for: skip-link navigation; accordion expand/collapse and focus; filter-button aria-pressed state; search and…
✅ Passed checks (9 passed)
Check name Status Explanation
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Breaking Change Declared ✅ Passed The description contains exactly one template statement: "This is not a breaking change." The reviewed diff changes only .gitignore, package.json, package-lock.json, and adds `tasks/shared-compo…
No New Runtime Dependency ✅ Passed package.json keeps the same dependencies field: only lit: 3.3.3 is present at both base and head. The PR changes no files under packages/**/src/**, so it introduces no new production JavaScrip…
Regression Test Targets The Change ✅ Passed PASS: The authoritative PR diff changes only .gitignore, package.json, package-lock.json, and adds tasks/shared-components.js. It does not change production JavaScript under `packages/**/src/*…
New Api Surface Follow-Ups ✅ Passed PASS: The check is not applicable. The authoritative diff changes only .gitignore, package metadata, and the new local report task; it adds no $theme-* setting, public Sass mixin/function, Sass so…
Theme Token Discipline ✅ Passed PASS. The authoritative pull-request diff changes only .gitignore, package-lock.json, package.json, and tasks/shared-components.js. It changes no *.scss file under packages/, so the theme-…
Title check ✅ Passed The title follows the required Conventional Commit format with the lowercase type "chore", scope "tasks", colon, and concise description. It accurately describes the added shared component analysis re…
Description check ✅ Passed The description clearly explains the new npm script, dependency scanning task, generated report, output location, implementation, limitations, and testing steps. It is directly related to the changese…
Full details: Accessibility Verification Declared

Explanation

The check applies because the new report adds ARIA attributes, tabindex, skip navigation, accordion buttons, filter-button state updates, and interactive filtering. The PR description does not name any assistive technology or browser combinations, and the checklist sub-item remains blank. It also does not state what was verified for those combinations.

Resolution

Add a test matrix to the PR description. Name each assistive technology and browser combination used, and state what was verified for: skip-link navigation; accordion expand/collapse and focus; filter-button aria-pressed state; search and filter updates; table keyboard access and scrolling; hidden table rows; and the search label and landmark associations. Do not leave the physical-device and assistive-technology checklist entry blank.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@poluru-labs

poluru-labs commented Oct 2, 2026

Copy link
Copy Markdown
Author

Please review this PR when you all get a time.

@github-actions github-actions Bot mentioned this pull request Oct 2, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

Needs: Author Response 🔴 Waiting on a specific author action; also used by commit-signature automation.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@poluru-labs