---
title: "ESG Reporting: GRI, ICMM and BRSR"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{ESG Reporting: GRI, ICMM and BRSR}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
library(MineSDG)
```

MineSDG v0.4.0 turns the site KPI engine into a reporting engine.
Instead of chaining `calculate_*()` primitives, one call produces a
framework report:

```{r}
rep <- generate_gri_report(demo_mine_sites, site_id = "CU-ATAC",
                           years = 2022:2024)
rep
```

## The disclosure bundle

Every report is built from a **disclosure bundle** -- the only interface
between the scoring engine and the reporting layer:

```
Mine KPI Data -> KPI Engine -> Score Engine -> Disclosure Bundle
  -> Framework Mapping -> Report Generator
```

`compile_site_disclosures()` runs `score_site_sdg()` once per year and
assembles KPI values, scores, validated raw inputs, year-on-year deltas
and your narrative text. Report generators never call KPI calculators
directly, which guarantees a single source of truth and zero duplicate
calculations.

```{r}
bundle <- compile_site_disclosures(
  demo_mine_sites, site_id = "CU-ATAC", years = 2022:2024,
  narratives = list(
    nar_water_mgmt = "Site water is managed under a catchment-level
      stewardship plan with quarterly community review."),
  entity_meta = list(company = "Atacama Copper SpA"))
bundle

bundle_kpi(bundle, "ghg_intensity")
bundle_raw(bundle, "ghg_scope1_t")
bundle_score(bundle, "goal_8")
```

## Framework mappings are data

Each framework ships as a crosswalk dataset with a shared schema.
Adding or amending a disclosure means editing data
(`data-raw/make_crosswalks.R`), not code:

```{r}
framework_crosswalk("gri")[1:6, c("disclosure_id", "disclosure_title",
                                  "source_type", "source_id")]
```

The generic mapper resolves every disclosure to a value and an honest
status -- `reported`, `partial`, `narrative_provided`,
`narrative_required` or `not_in_scope`. Reports never fabricate:

```{r}
m <- map_bundle_to_framework(bundle, "gri")
m
```

## GRI

`generate_gri_report()` covers GRI 302, 303, 304, 305, 306, 403 and
413, and produces the content index assurance teams ask for:

```{r}
head(gri_content_index(rep), 8)
```

## ICMM

`generate_icmm_report()` adds a board scorecard, a traffic-light
assessment (a pure reclassification of existing 0-100 KPI scores) and
data-driven recommendations from `icmm_recommendation_rules`:

```{r}
icmm <- generate_icmm_report(demo_mine_sites, site_id = "CU-ATAC",
                             years = 2023:2024)
icmm$extras$traffic_lights[, c("kpi_id", "value", "score", "light")]
icmm$extras$recommendations[, c("principle", "recommendation")]
```

## BRSR

The SEBI BRSR generators reuse the same bundle. Supply
`entity_meta$fx_usd_inr` to convert monetary lines to INR lakh --
without it, those lines are flagged `partial`/`not_in_scope` rather
than estimated:

```{r}
kpis <- generate_brsr_kpis(
  demo_mine_sites, site_id = "CO-JHAR", years = 2023:2024,
  entity_meta = list(fx_usd_inr = 83.2))
kpis[, c("disclosure_id", "disclosure_title", "value", "status")]
```

`generate_brsr_report()`, `generate_brsr_sectionA()` and
`generate_brsr_sectionB()` are views over the same single mapping
computation.

## Rendering

Reports are plain R objects; rendering is optional and gated on
Suggests packages:

```{r, eval = FALSE}
# HTML / PDF / DOCX via the packaged Quarto templates
render_minesdg_report(rep, "gri_2024.html", format = "html")
render_minesdg_report(rep, "gri_2024.pdf",  format = "pdf")

# Styled Excel workbook of the disclosure tables
write_report_xlsx(rep, "gri_2024.xlsx")

# One-liner: generate and render together
generate_brsr_report(demo_mine_sites, site_id = "CO-JHAR",
                     years = 2023:2024, output = "brsr.docx",
                     format = "docx")
```

## Portfolio and radar views

```{r, fig.width = 7, fig.height = 5}
score_portfolio_sdg(demo_mine_sites)[year == 2024]
plot_sdg_radar(bundle)
plot_domain_radar(bundle)
```

The dashboard (`run_minesdg_dashboard()`) exposes the same functions
interactively, including new Benchmark and Radar tabs.