Skip to content

docs: add agent guidance and threat model - #2828

Open
smoelius wants to merge 1 commit into
validatorjs:masterfrom
trail-of-forks:add-agents-threat-model
Open

docs: add agent guidance and threat model#2828
smoelius wants to merge 1 commit into
validatorjs:masterfrom
trail-of-forks:add-agents-threat-model

Conversation

@smoelius

Copy link
Copy Markdown
Contributor

Add AGENTS.md with repository-specific guidance for coding agents, including the
project layout, build and test workflows, change discipline, and standards for
security analysis and reproduction.

Add THREAT_MODEL.md to document validator.js's security boundaries, expected
properties, threat scenarios, possible controls, and non-binding guidance for
reviewing and classifying findings. The threat model also clarifies the
responsibilities retained by applications integrating validator.js.

This PR changes documentation only; it does not alter the public API, runtime
behavior, generated distributions, or package contents.

References used to describe the project and its security and release boundaries:

Checklist

  • PR contains only changes related; no stray files, etc.
  • README updated (where applicable)
  • Tests written (where applicable)
  • References provided in PR (where applicable)

@smoelius smoelius changed the title Add AGENTS.md and THREAT_MODEL.md docs: add agent guidance and threat model Jul 27, 2026
@codecov

codecov Bot commented Jul 27, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (cca32d6) to head (f6f1b58).

Additional details and impacted files
@@            Coverage Diff            @@
##            master     #2828   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files          114       114           
  Lines         2600      2600           
  Branches       659       659           
=========================================
  Hits          2600      2600           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@tux-tn tux-tn left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overall, this is a useful addition, especially as we receive more AI-assisted contributions. I also added a suggestion regarding the Node.js guidance

Comment thread AGENTS.md

- Use npm for the official build and test path.
- Install development dependencies with `npm install --legacy-peer-deps`, as documented in `CONTRIBUTING.md` and used by CI.
- Prefer Node.js 24 for local work. CI also tests Node.js 8, 10, 12, 14, 16, 18, 20, and 22, so avoid syntax or runtime APIs unsupported by the intended compatibility range.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we make this guidance more generic and avoid hard-coding the CI matrix and future maintenance?
For example:

Suggested change
- Prefer Node.js 24 for local work. CI also tests Node.js 8, 10, 12, 14, 16, 18, 20, and 22, so avoid syntax or runtime APIs unsupported by the intended compatibility range.
- Prefer the latest Node.js LTS release for local development. When adding syntax or runtime APIs, follow the compatibility range declared in `package.json` and verify compatibility with the Node.js versions supported by CI.

This keeps the guidance current as the supported Node.js versions and CI matrix change.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants