PurviewIntegrations

# AGENTS.md — Agent Router

This file is the single entry point for AI agents (Copilot CLI, Copilot Chat, Claude,
Cursor, etc.) working in this repository. It points to the tooling, conventions, and
build/test loop an agent needs to make a change and validate it before pushing.

## What this repo is

**Purview GitHub Action** — a TypeScript GitHub Action that scans repository files on push
/ pull request and sends them to Microsoft Purview for data governance and compliance
tracking. It authenticates with Azure via GitHub OIDC, processes changed files, builds
chunked payloads, and calls the Purview API with retry/backoff.

Entry point: [`src/index.ts`](src/index.ts). Bundled output: [`dist/`](dist/) (generated by
`ncc`, committed). Action metadata: [`action.yml`](action.yml).

## Discoverable context

| Topic | Source |
| --- | --- |
| Product overview, features, usage | [`README.md`](README.md) |
| End-to-end setup (Entra app, OIDC, secrets, workflow install) | [`Instructions.md`](Instructions.md) |
| Code style, structure, and test patterns | [`docs/conventions.md`](docs/conventions.md) |
| GitHub Actions best practices (action.yml, inputs/outputs, secrets, dist sync, workflow security) | [`docs/github-actions.md`](docs/github-actions.md) |
| Test framework, layout, and `@actions/*` mocking pattern | [`docs/testing-patterns.md`](docs/testing-patterns.md) |
| PR & ADO work-item telemetry tagging (mandatory) | [`.github/instructions/telemetry.instructions.md`](.github/instructions/telemetry.instructions.md) |
| Agent guardrails (PR size, etc.) | [`.github/copilot-instructions.md`](.github/copilot-instructions.md) |
| PR template | [`.github/pull_request_template.md`](.github/pull_request_template.md) |

## Build & test loop

The repeatable build-and-test loop lives in [`package.json`](package.json) scripts and is
documented in the README **Development** section. Run these from the repo root:

```bash
npm install        # install dependencies
npm run build      # tsc compile (src -> intermediate)
npm run package    # ncc bundle into dist/
npm run test       # jest (ts-jest), runs all tests under tests/**
npm run lint       # eslint over src/**/*.ts
```

For a single-command run of the whole loop, use the verify script:

```powershell
pwsh scripts/verify.ps1   # install deps, build, package, test (+ best-effort lint)
```

A [`.husky/pre-commit`](.husky/pre-commit) hook runs `npm test`, rebuilds, and re-stages the
bundled `dist/` files on every commit. CI runs `npm ci && npm test` on push to `main` and on
every pull request (see [`.github/workflows/tests.yml`](.github/workflows/tests.yml)), and a
separate [`check-dist`](.github/workflows/check-dist.yml) job rebuilds the bundle and fails if
the committed `dist/` is out of sync with `src/`. This action runs the committed
`dist/index.js`, not the TypeScript source — see [`docs/github-actions.md`](docs/github-actions.md)
for the full set of GitHub Actions conventions (action.yml, inputs/outputs, secret handling,
and workflow security).

## Verification / Definition of Done

Before opening a PR, an agent should:

1. Run [`scripts/verify.ps1`](scripts/verify.ps1) — installs dependencies, compiles TypeScript,
   bundles the action with ncc, and runs the full jest suite (equivalent to
   `npm run build && npm run package && npm run test`).
2. Commit so the `.husky/pre-commit` hook rebuilds and stages `dist/`.
3. Apply the mandatory telemetry labels and PR-description footer from
   [`.github/instructions/telemetry.instructions.md`](.github/instructions/telemetry.instructions.md).

## PR conventions

Titles are at the author's discretion. Tagging is **not** optional — every PR must carry the
two required labels and the `pr-telemetry` description footer defined in
[`.github/instructions/telemetry.instructions.md`](.github/instructions/telemetry.instructions.md).
Keep PRs reasonably sized; see [`.github/copilot-instructions.md`](.github/copilot-instructions.md).