forked from mirrors/kingfisher
41 lines
2.5 KiB
Markdown
41 lines
2.5 KiB
Markdown
# AGENTS.md
|
|
|
|
Guidance for editing the local report viewer under `docs/viewer/`.
|
|
|
|
## Scope
|
|
|
|
- Applies to `docs/viewer/` and all files under it.
|
|
- This file overrides broader documentation guidance for this subtree.
|
|
|
|
## Current Architecture
|
|
|
|
- The shipped viewer is the single-file app in `index.html`.
|
|
- Treat `index.html` as the authoritative implementation for the UI, parsing, and rendering logic.
|
|
- `sample-report.json` is the canonical example payload for native Kingfisher viewer data.
|
|
- `app.js`, `viewer.js`, and `viewer.css` may exist as older or non-authoritative assets. Do not assume changes there affect the shipped viewer unless you also update how the app is loaded.
|
|
|
|
## Editing Expectations
|
|
|
|
- Prefer targeted edits over broad refactors. This file is large, so keep changes localized and easy to review.
|
|
- Keep new parsing or normalization logic grouped into small helper functions instead of scattering format-specific conditionals throughout the file.
|
|
- Preserve the distinction between native Kingfisher reports and imported third-party reports in both data handling and UI messaging.
|
|
- Do not imply feature parity for imported reports when native-only features such as `access_map`, validate commands, revoke commands, or blast-radius linking are unavailable.
|
|
- Prefer ASCII when editing text unless the file already relies on another character.
|
|
|
|
## Data Model Guidance
|
|
|
|
- Native viewer inputs should continue to normalize around the Kingfisher envelope shape: `findings`, optional `access_map`, and optional metadata.
|
|
- When supporting imported formats, map them into the viewer envelope instead of building parallel rendering paths.
|
|
- Keep fingerprint behavior stable and explicit. If imported reports need synthetic fingerprints, use a deterministic approach and document the fidelity limits in the UI or docs.
|
|
- Preserve graceful handling of both JSON and JSONL inputs.
|
|
|
|
## UI Guidance
|
|
|
|
- Keep imported-report limitations visible in the viewer when access-map data or command workflows are unavailable.
|
|
- Prefer small explanatory notices and empty states over hiding entire sections without explanation.
|
|
- Maintain client-side-only behavior. Do not add network calls from the viewer except for the existing local `GET /report` loading path used by `kingfisher view`.
|
|
|
|
## Validation
|
|
|
|
- After substantive edits to `index.html`, run a syntax check on the embedded JavaScript by extracting the `<script>` block and using `node --check`.
|
|
- For doc or sample changes, make sure examples still match the current viewer behavior and accepted report formats.
|