scorecard items

CONTRIBUTING.md

@@ -2,14 +2,14 @@
 
 All pull requests are welcome, there are just a few guidelines you need to follow.
 
-When contributing to this repository, please first discuss the change by creating a new [issue](https://github.com/microsoft/mha/issues) or by replying to an existing one.
+When contributing to this repository, please first discuss the change by creating a new [issue](https://github.com/microsoft/MHA/issues) or by replying to an existing one.
 
 ## GETTING STARTED
 
 * Make sure you have a [GitHub account](https://github.com/signup/free).
 * Fork the repository, you can [learn about forking on Github](https://help.github.com/articles/fork-a-repo)
-* [Clone the repro to your local machine](https://help.github.com/articles/cloning-a-repository/) like so:  
-```git clone --recursive https://github.com/microsoft/mha.git```
+* [Clone the repo to your local machine](https://help.github.com/articles/cloning-a-repository/) like so:  
+```git clone --recursive https://github.com/microsoft/MHA.git```
 
 ## MAKING CHANGES
 
@@ -19,6 +19,7 @@ When contributing to this repository, please first discuss the change by creatin
 ```git checkout -b u/username/topic main```  
   * *Make sure to substitute your own name and topic in this command* *
 * Once you have a branch, make your changes and commit them to the local branch.
+* If your change adds or modifies major functionality, add or update automated Jest tests in the same pull request.
 * All submissions require a review and pull requests are how those happen. Consult
 [GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
 information on pull requests.
@@ -27,6 +28,26 @@ information on pull requests.
 
 * Push your changes to a topic branch in your fork of the repository.
 
+## TEST POLICY
+
+* Major functionality changes must include or update automated Jest tests in the same pull request.
+* Test updates must meet coverage requirements.
+* See [TESTING.md](./TESTING.md) for test commands, coverage thresholds, and CI details.
+
+## BEFORE YOU OPEN A PULL REQUEST
+
+* Install dependencies: `npm install`
+* Start local development server when validating UI behavior: `npm run dev-server`
+* Run lint locally and fix all issues: `npm run lint`
+* Run tests locally and confirm pass: `npm test`
+* Include related tests in the same PR when behavior changes and verify coverage requirements are met.
+
+## SECURITY REPORTING
+
+* Do not report security vulnerabilities in public issues.
+* Follow the Microsoft coordinated vulnerability disclosure policy:
+  * <https://github.com/microsoft/.github/blob/main/SECURITY.md>
+
 ## PUSH TO YOUR FORK AND SUBMIT A PULL REQUEST
 
 At this point you're waiting on the code/changes to be reviewed.

README.md

@@ -7,13 +7,46 @@
 [![Jest](https://github.com/microsoft/MHA/actions/workflows/jest.yml/badge.svg)](https://github.com/microsoft/MHA/actions/workflows/jest.yml)  
 [![OpenSSF
 Scorecard](https://api.securityscorecards.dev/projects/github.com/microsoft/MHA/badge)](https://scorecard.dev/viewer/?uri=github.com%2Fmicrosoft%2FMHA)  
-[![OpenSSF Best Practices](https://bestpractices.coreinfrastructure.org/projects/7511/badge)](https://bestpractices.coreinfrastructure.org/projects/7511)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/7511/badge)](https://www.bestpractices.dev/projects/7511)
 
 Message Header Analyzer mail app.
 
 This is the source for the Message Header Analyzer. Install the app from the store here:
 <https://appsource.microsoft.com/en-us/product/office/WA104005406>
 
+## Obtain, Provide Feedback, and Contribute
+
+- Obtain: Install Message Header Analyzer from AppSource: <https://appsource.microsoft.com/en-us/product/office/WA104005406>
+- Provide feedback (bugs/enhancements): Open a GitHub issue: <https://github.com/microsoft/MHA/issues>
+- Contribute code/docs: Submit a pull request to this repository and follow the contribution process in `CONTRIBUTING.md`: <https://github.com/microsoft/MHA/blob/main/CONTRIBUTING.md>
+
+## External Interface Reference
+
+This section documents the external interface of the software, including where it is accessed and the expected inputs and outputs.
+
+### End-user interface
+
+- AppSource install endpoint: <https://appsource.microsoft.com/en-us/product/office/WA104005406>
+- Standalone web interface URL: <https://mha.azurewebsites.net/pages/mha.html>
+- Outlook add-in interface: opened from an Outlook message in supported Outlook clients.
+
+### Functional input/output
+
+- Primary input: the currently selected email message in Outlook.
+- Data input read by the app: transport message headers retrieved through the Outlook/EWS mailbox APIs.
+- Primary output: parsed and human-readable header analysis shown in the MHA UI.
+
+### Local development/test interface
+
+- Local standalone page: <https://localhost:44336/Pages/mha.html>
+- Local unit test runner page: <https://localhost:44336/Pages/test/>
+- Local coverage report page: <https://localhost:44336/Pages/coverage/lcov-report/>
+
+### Interface behavior notes
+
+- Required Outlook permission level for header retrieval: ReadWriteMailbox.
+- The app consumes Outlook mailbox APIs and does not expose a separate public REST API.
+
 ## Installation Procedure
 
 Because MHA requires the ReadWriteMailbox permission it can only be installed by the Administrator through the Exchange admin center or by a user as a custom addon. Here are some steps I put together:
@@ -44,8 +77,7 @@ Here is a standalone Message Header Analyzer running the same backend code as th
 
 ## Unit Tests
 
-- [Unit tests](https://mha.azurewebsites.net/Pages/test)
-- [Code coverage](https://mha.azurewebsites.net/Pages/coverage/lcov-report)
+- Testing policy, local test workflow, coverage requirements, and CI details are documented in [TESTING.md](./TESTING.md).
 
 ## Mobile
 
@@ -65,14 +97,6 @@ For both IOS and Android click open an email, then press the three dots under th
 - Manual build: `npm run build`
 - For continuous build on changes, you can use watch: `npm run watch`
 
-### Unit Testing
-
-- Start the dev server: `npm run dev-server`
-- Run unit tests from command line: `npm run test`
-- View test results here: <https://localhost:44336/Pages/test/>
-- View code coverage here: <https://localhost:44336/Pages/coverage/lcov-report/>
-- After changing source you will need to `npm run test` again.
-
 ### Live site testing
 
 - Start the dev server: `npm run dev-server`

TESTING.md

@@ -0,0 +1,37 @@
+# TESTING
+
+This document describes MHA testing policy, local test execution, coverage requirements, and CI validation.
+
+## Test policy
+
+- Major functionality changes must include or update automated Jest tests in the same pull request.
+- When behavior changes, contributors are expected to add or update tests that validate the new behavior.
+- Automated tests must include assertion checks (Jest `expect(...)`) for behavior verification.
+- Pull requests are validated by CI running `npm test`.
+- Global minimum coverage thresholds are enforced in `jest.config.ts`:
+  - branches: 35
+  - functions: 40
+  - lines: 40
+  - statements: 40
+
+## Local testing workflow
+
+1. Install dependencies: `npm install`
+2. Start local development server when validating UI behavior: `npm run dev-server`
+3. Run lint and fix issues: `npm run lint`
+4. Run tests: `npm test`
+
+## Test outputs
+
+- Local unit test runner page: <https://localhost:44336/Pages/test/>
+- Local coverage report page: <https://localhost:44336/Pages/coverage/lcov-report/>
+- Hosted unit test report: <https://mha.azurewebsites.net/Pages/test>
+- Hosted code coverage report: <https://mha.azurewebsites.net/Pages/coverage/lcov-report>
+
+## CI test validation
+
+- Workflow: `.github/workflows/jest.yml`
+- Triggered on pull requests, merge groups, workflow dispatch, and pushes to `main`.
+- CI executes:
+  - `npm ci`
+  - `npm test`