Skip to content

Commit f7ebd78

Browse files
orenlaborenlab
committed
chore(docs): update AGENTS.md
1 parent 3be4937 commit f7ebd78

1 file changed

Lines changed: 33 additions & 13 deletions

File tree

‎AGENTS.md‎

Lines changed: 33 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,8 @@ Key artifacts:
5959

6060
- `codeclone.baseline.json` — trusted baseline snapshot (for CI comparisons)
6161
- `.cache/codeclone/cache.json` — analysis cache (integrity-checked)
62-
- `.cache/codeclone/report.html|report.json|report.txt` — reports
62+
- `.cache/codeclone/report.html|report.json|report.md|report.sarif|report.txt` — reports
63+
- `docs/`, `mkdocs.yml`, `.github/workflows/docs.yml` — published documentation site and docs build pipeline
6364

6465
---
6566

@@ -72,6 +73,11 @@ uv run pre-commit run --all-files
7273
```
7374

7475
If you touched baseline/cache/report contracts, also run the repo’s audit runner (or the scenario script if present).
76+
If you touched `docs/`, `mkdocs.yml`, docs publishing workflow, or sample-report generation, also run:
77+
78+
```bash
79+
uv run --with mkdocs --with mkdocs-material mkdocs build --strict
80+
```
7581

7682
---
7783

@@ -151,6 +157,8 @@ Reports come in:
151157

152158
- HTML (`--html`)
153159
- JSON (`--json`)
160+
- Markdown (`--md`)
161+
- SARIF (`--sarif`)
154162
- Text (`--text`)
155163

156164
### Report invariants
@@ -284,8 +292,10 @@ Architecture is layered, but grounded in current code (not aspirational diagrams
284292
trusted comparison state and optimization state.
285293
- **Canonical report + projections** (`codeclone/report/json_contract.py`, `codeclone/report/*.py`) converts analysis
286294
facts to deterministic, contract-shaped outputs.
287-
- **HTML/UI rendering** (`codeclone/html_report.py`, `codeclone/_html_*.py`, `codeclone/templates.py`) renders views
288-
from report/meta facts.
295+
- **HTML/UI rendering** (`codeclone/html_report.py`, `codeclone/_html_report/*`, `codeclone/_html_*.py`,
296+
`codeclone/templates.py`) renders views from report/meta facts.
297+
- **Documentation/publishing surface** (`docs/`, `mkdocs.yml`, `.github/workflows/docs.yml`,
298+
`scripts/build_docs_example_report.py`) publishes contract docs and the live sample report.
289299
- **Tests-as-spec** (`tests/`) lock behavior, contracts, determinism, and architecture boundaries.
290300

291301
Non-negotiable interpretation:
@@ -323,10 +333,17 @@ Use this map to route changes to the right owner module.
323333
change belongs here.
324334
- `codeclone/report/*.py` (other modules) — deterministic projections/format transforms (
325335
text/markdown/sarif/derived/findings/suggestions); avoid injecting new analysis heuristics here.
326-
- `codeclone/html_report.py` — HTML presentation layer from report/meta payload; no hidden analysis decisions.
336+
- `codeclone/html_report.py` — public HTML facade/re-export surface; preserve backward-compatible imports here; do not
337+
grow section/layout logic in this module.
338+
- `codeclone/_html_report/*` — actual HTML assembly, context shaping, tabs, sections, and overview/navigation behavior;
339+
change report layout and interactive HTML UX here, not in the facade.
340+
- `codeclone/_html_*.py` — shared HTML badges, CSS, JS, escaping, snippets, and data-attrs; keep these as render-only
341+
helpers.
327342
- `codeclone/models.py` — shared typed models crossing modules; keep model changes contract-aware.
328343
- `codeclone/domain/*.py` — centralized domain taxonomies/IDs (families, categories, source scopes, risk/severity
329344
levels); use these constants in pipeline/report/UI instead of scattering raw literals.
345+
- `docs/`, `mkdocs.yml`, `.github/workflows/docs.yml`, `scripts/build_docs_example_report.py` — docs-site source,
346+
publication workflow, and live sample-report generation; keep published docs aligned with code contracts.
330347
- `tests/` — executable specification: architecture rules, contracts, goldens, invariants, regressions.
331348

332349
## 14) Dependency direction
@@ -356,7 +373,8 @@ Inline suppressions are explicit local policy, not analysis truth.
356373
- Supported syntax is `# codeclone: ignore[rule-id,...]` via `codeclone/suppressions.py`.
357374
- Binding scope is declaration-only (`def`, `async def`, `class`) using:
358375
- leading comment on the line immediately before declaration
359-
- inline comment on declaration line
376+
- inline comment on the declaration header start line
377+
- inline comment on the declaration header closing line for multiline signatures
360378
- Binding is target-specific (`filepath`, `qualname`, declaration span, kind). No file-wide/global implicit scope.
361379
- Unknown/malformed directives are ignored safely; analysis must not fail because of suppression syntax issues.
362380
- Current active semantic effect is dead-code suppression (`dead-code`) through `extractor.py` →
@@ -371,14 +389,15 @@ Prefer explicit inline suppressions for runtime/dynamic false positives instead
371389

372390
If you change a contract-sensitive zone, route docs/tests/approval deliberately.
373391

374-
| Change zone | Must update docs | Must update tests | Explicit approval required when | Contract-change trigger |
375-
|--------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
376-
| Baseline schema/trust/integrity (`codeclone/baseline.py`) | `docs/book/06-baseline.md`, `docs/book/14-compatibility-and-versioning.md`, `docs/book/appendix/b-schema-layouts.md`, `CHANGELOG.md` | `tests/test_baseline.py`, CI/CLI behavior tests (`tests/test_cli_inprocess.py`, `tests/test_cli_unit.py`) | schema/trust semantics, compatibility windows, payload integrity logic change | baseline key layout/status semantics/compat rules change |
377-
| Cache schema/profile/integrity (`codeclone/cache.py`) | `docs/book/07-cache.md`, `docs/book/appendix/b-schema-layouts.md`, `CHANGELOG.md` | `tests/test_cache.py`, pipeline/CLI cache integration tests | cache schema/status/profile compatibility semantics change | cache payload/version/status semantics change |
378-
| Canonical report JSON shape (`codeclone/report/json_contract.py`, report projections) | `docs/book/08-report.md` (+ `docs/book/10-html-render.md` if rendering contract impacted), `CHANGELOG.md` | `tests/test_report.py`, `tests/test_report_contract_coverage.py`, `tests/test_report_branch_invariants.py`, relevant report-format tests | finding/meta/summary schema changes | stable JSON fields/meaning/order guarantees change |
379-
| CLI flags/help/exit behavior (`codeclone/cli.py`, `_cli_*`, `contracts.py`) | `docs/book/09-cli.md`, `docs/book/03-contracts-exit-codes.md`, `README.md`, `CHANGELOG.md` | `tests/test_cli_unit.py`, `tests/test_cli_inprocess.py`, `tests/test_cli_smoke.py` | exit-code semantics, script-facing behavior, flag contracts change | user-visible CLI contract changes |
380-
| Fingerprint-adjacent analysis (`extractor/cfg/normalize/grouping`) | `docs/book/05-core-pipeline.md`, `docs/cfg.md`, `docs/book/14-compatibility-and-versioning.md`, `CHANGELOG.md` | `tests/test_fingerprint.py`, `tests/test_extractor.py`, `tests/test_cfg.py`, golden tests (`tests/test_detector_golden.py`, `tests/test_golden_v2.py`) | always (see Section 1.6) | clone identity / NEW-vs-KNOWN / fingerprint inputs change |
381-
| Suppression semantics/reporting (`suppressions`, extractor dead-code wiring, report/UI counters) | `docs/book/19-inline-suppressions.md`, `docs/book/16-dead-code-contract.md`, `docs/book/08-report.md`, and interface docs if surfaced (`09-cli`, `10-html-render`) | `tests/test_suppressions.py`, `tests/test_extractor.py`, `tests/test_metrics_modules.py`, `tests/test_pipeline_metrics.py`, report/html/cli tests | declaration scope semantics, rule effect, or contract-visible counters/fields change | suppression changes alter active finding output or contract-visible report payload |
392+
| Change zone | Must update docs | Must update tests | Explicit approval required when | Contract-change trigger |
393+
|-------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
394+
| Baseline schema/trust/integrity (`codeclone/baseline.py`) | `docs/book/06-baseline.md`, `docs/book/14-compatibility-and-versioning.md`, `docs/book/appendix/b-schema-layouts.md`, `CHANGELOG.md` | `tests/test_baseline.py`, CI/CLI behavior tests (`tests/test_cli_inprocess.py`, `tests/test_cli_unit.py`) | schema/trust semantics, compatibility windows, payload integrity logic change | baseline key layout/status semantics/compat rules change |
395+
| Cache schema/profile/integrity (`codeclone/cache.py`) | `docs/book/07-cache.md`, `docs/book/appendix/b-schema-layouts.md`, `CHANGELOG.md` | `tests/test_cache.py`, pipeline/CLI cache integration tests | cache schema/status/profile compatibility semantics change | cache payload/version/status semantics change |
396+
| Canonical report JSON shape (`codeclone/report/json_contract.py`, report projections) | `docs/book/08-report.md` (+ `docs/book/10-html-render.md` if rendering contract impacted), `docs/sarif.md` when SARIF changes, `CHANGELOG.md` | `tests/test_report.py`, `tests/test_report_contract_coverage.py`, `tests/test_report_branch_invariants.py`, relevant report-format tests | finding/meta/summary schema changes | stable JSON fields/meaning/order guarantees change |
397+
| CLI flags/help/exit behavior (`codeclone/cli.py`, `_cli_*`, `contracts.py`) | `docs/book/09-cli.md`, `docs/book/03-contracts-exit-codes.md`, `README.md`, `CHANGELOG.md` | `tests/test_cli_unit.py`, `tests/test_cli_inprocess.py`, `tests/test_cli_smoke.py` | exit-code semantics, script-facing behavior, flag contracts change | user-visible CLI contract changes |
398+
| Fingerprint-adjacent analysis (`extractor/cfg/normalize/grouping`) | `docs/book/05-core-pipeline.md`, `docs/cfg.md`, `docs/book/14-compatibility-and-versioning.md`, `CHANGELOG.md` | `tests/test_fingerprint.py`, `tests/test_extractor.py`, `tests/test_cfg.py`, golden tests (`tests/test_detector_golden.py`, `tests/test_golden_v2.py`) | always (see Section 1.6) | clone identity / NEW-vs-KNOWN / fingerprint inputs change |
399+
| Suppression semantics/reporting (`suppressions`, extractor dead-code wiring, report/UI counters) | `docs/book/19-inline-suppressions.md`, `docs/book/16-dead-code-contract.md`, `docs/book/08-report.md`, and interface docs if surfaced (`09-cli`, `10-html-render`) | `tests/test_suppressions.py`, `tests/test_extractor.py`, `tests/test_metrics_modules.py`, `tests/test_pipeline_metrics.py`, report/html/cli tests | declaration scope semantics, rule effect, or contract-visible counters/fields change | suppression changes alter active finding output or contract-visible report payload |
400+
| Docs site / sample report publication (`docs/`, `mkdocs.yml`, `.github/workflows/docs.yml`, `scripts/build_docs_example_report.py`) | `docs/README.md`, `docs/publishing.md`, `docs/examples/report.md`, and any contract pages surfaced by the change, `CHANGELOG.md` when user-visible behavior changes | `mkdocs build --strict`, sample-report generation smoke path, and relevant report/html tests if generated examples or embeds change | published docs navigation, sample-report generation, or Pages workflow semantics change | published documentation behavior or sample-report generation contract changes |
382401

383402
Golden rule: do not “fix” failures by snapshot refresh unless the underlying contract change is intentional, documented,
384403
and approved.
@@ -411,6 +430,7 @@ Policy:
411430
- Baseline schema/trust semantics/integrity compatibility (`2.0` baseline contract family).
412431
- Cache schema/status/profile compatibility/integrity (`CACHE_VERSION` contract family).
413432
- Canonical report JSON schema/payload semantics (`REPORT_SCHEMA_VERSION` contract family).
433+
- Documented report projections and their machine/user-facing semantics (HTML/Markdown/SARIF/Text).
414434
- Documented finding families/kinds/ids and suppression-facing report fields.
415435
- Metrics baseline schema/compatibility where used by CI/gating.
416436
- Benchmark schema/outputs if consumed as a reproducible contract surface.

0 commit comments

Comments
 (0)