docs: update Learn page statistics and add CI/CD for auto-updates

[parthrohit22]

What problem does this solve?

docs/learn/index.html hardcodes repository statistics that were correct when the page was
written and have drifted since. The page currently advertises:

Statistic	Page says	Actual
Azure scan rules	39	66
CLI remediation playbooks	39	66
High-severity checks	22	38
Hero terminal ("dynamic checks")	39	66
Severity card (HIGH / MEDIUM / LOW)	22 / 13 / 4	38 / 23 / 4
"Coverage by category" chart	omits Supply Chain and Kubernetes, Identity undercounted at 4	9 categories, Identity 15

README.md carries the same drift in four more places: the Misconfiguration Scanner and
Remediation Playbooks rows of the feature table, and both the Scanner Engine and
Azure CLI Playbooks nodes of the Mermaid architecture diagram (all reading 51).

Two problems follow from this:

1. The Learn page understates the project. New contributors and evaluators land on it and
   see roughly half the coverage OpenShield actually ships.
2. It will drift again. Every scanner-rule PR that merges to dev makes the numbers more
   wrong, and nothing in CI notices. Manual correction is not sustainable at the rate rules
   are being added.

Describe the solution

Two parts:

1. Correct the current numbers in docs/learn/index.html — the headline counts, the
pipeline step, the section title, the intro paragraph, the hero terminal, the severity card
and the category chart all repeat the same figures and must be updated together. README.md
needs the same treatment for its four stale counts.

2. Add a GitHub Actions workflow that keeps them correct. On every push to dev:

• Derive the counts from the codebase rather than from a checked-in constant:
  • rule count from scanner/rules/ (files that declare a RULE_ID)
  • playbook count from playbooks/cli/*.sh
  • severity counts from each rule's SEVERITY value
• Rewrite the statistics in docs/learn/index.html and README.md
• Commit and push only when something actually changed, tagged [skip ci] so the workflow
  cannot retrigger itself

The update script must be idempotent: running it on an already-current page produces no diff.

Alternatives considered

• Keep updating the page by hand. Rejected — this issue exists precisely because that
  failed. The numbers went stale within a few release cycles.
• A CI check that fails the build when the numbers are stale, rather than auto-committing.
  Lower blast radius and no bot commits on dev, but it pushes the chore onto every
  contributor whose PR happens to change a count. Worth revisiting if the auto-commit
  approach turns out to conflict with branch protection on dev.
• Render the statistics client-side from a generated JSON file. Cleaner separation, but
  the Learn page is deliberately a single static HTML file with no build step, and adding one
  is out of proportion to the problem.

Additional context

• Affected files: docs/learn/index.html, README.md
• New files: .github/workflows/update-learn-page.yml, .github/scripts/update_learn_page.py
• Implemented in PR docs: update learn page statistics and add CI/CD workflow #230
• No scanner, API, or frontend behaviour changes; documentation and CI only

[parthrohit22]

I would like to work on this

[parthrohit22]

Status check: PR #230 does not fully close this out

PR #230 corrects the five headline metric tiles, the pipeline step, the rules-section title,
and the rules-section intro paragraph in docs/learn/index.html, and adds a CI workflow that
keeps those specific strings current. That is real progress, but it is not the full fix — the
same page contradicts itself in three other places, and README.md is not touched at all.

Documenting the current state factually before more work lands on top of it.

Stale in docs/learn/index.html (not covered by the current script)

• Hero terminal block, line 755: <span class="cyan">39 dynamic checks</span>. This is
  above the fold — the first number a visitor sees is wrong.
• Severity distribution card, lines 868–870: 22 HIGH / 13 MEDIUM / 4 LOW. The actual
  breakdown is 38 HIGH / 22 MEDIUM / 4 LOW (see table below). After PR docs: update learn page statistics and add CI/CD workflow #230 the metric
  tile above this card already reads 38 for "High-severity checks" — so the page will assert
  two different HIGH counts in two different cards simultaneously.
• "Coverage by category" chart, lines 854–860: hardcoded rows sum to 39 (the old total),
  with bar widths as hand-set percentages. Two categories that exist in the codebase —
  Supply Chain (8 rules) and Kubernetes (6 rules) — are missing from the chart
  entirely. Identity is undercounted 4 vs. an actual 15. Network is undercounted 14 vs. 15.
• Line 872 claims KeyVault vs Key Vault naming is an inconsistency to clean up. The
  code has one spelling (CATEGORY = "KeyVault", no space) — the inconsistency is that the
  chart's hardcoded label uses Key Vault (with a space), not that the source is
  inconsistent with itself.

Stale in README.md (PR #230 does not touch this file)

• Misconfiguration Scanner feature-table row: "Runs 51 Azure security rules."
• Remediation Playbooks feature-table row: "(51 playbooks)."
• Mermaid architecture diagram: Scanner Engine\n51 Python rules node.
• Mermaid architecture diagram: Azure CLI Playbooks\n51 remediation scripts node.
• The new workflow in PR docs: update learn page statistics and add CI/CD workflow #230 only writes to docs/learn/index.html. README.md has no
  update mechanism, so it will never self-correct — it will just go stale again the next time
  a rule is added, exactly as docs/learn/index.html already has.

A claim that is now wrong

The "Known gaps" card (docs/learn/index.html, "Documentation drift" list) says:

Rule coverage and documentation counts are checked and updated with each release.

While the items above remain stale, this sentence overstates the current position. The page
previously admitted the drift more honestly than it does now.

A silent failure in the new script

.github/scripts/update_learn_page.py matches every replacement with a regex tied to exact
HTML wording (e.g. <span>Azure scan rules</span>). If a future edit rewords the surrounding
sentence, the regex matches zero times, content comes back unchanged, the script prints
"already current; nothing to do", and exits 0. CI goes green while the page is stale — the
failure is invisible unless someone diffs the rendered numbers against the filesystem by hand.

A real discrepancy in how rules are discovered (not just a style difference)

scanner/engine.py::load_rules() (the code that actually runs rules at scan time) discovers
rule modules with RULES_DIR.glob("*.py"), excluding only filenames starting with _. It
does not require an az_*.py prefix and does not require a RULE_ID. .github/workflows/ci.yml's
structure-validation job and update_learn_page.py both use the narrower az_*.py glob plus a
RULE_ID check. Today all three agree on 65 because scanner/rules/ happens to contain no
stray file that isn't either underscore-prefixed or az_-prefixed — but nothing enforces that.
A misplaced or leftover .py file with a scan() function would be loaded and executed by the
engine in production without being validated by CI or counted anywhere in documentation.

True numbers (derived from the filesystem, not from any doc)

Metric	Value
Rule files (scanner/rules/az_*.py with RULE_ID)	65
Playbooks (playbooks/cli/*.sh)	65
Rules with no matching playbook / playbooks with no matching rule	0 / 0
HIGH severity	38
MEDIUM severity	22
LOW severity	4
CRITICAL severity	1 (AZ-SC-005, not shown in the 3-box severity UI)
Rules with unparseable SEVERITY	0
Category: Identity	15
Category: Network	15
Category: Supply Chain	8
Category: Kubernetes	6
Category: KeyVault	5
Category: Storage	5
Category: Compute	4
Category: Database	4
Category: PostQuantum	3

Plan

Follow-up work on the PR #230 branch will:

1. Extend update_learn_page.py to also rewrite the hero terminal line, all three severity
   boxes (HIGH/MEDIUM/LOW, computed — not just HIGH), and fully regenerate the category chart
   (labels, counts, and bar widths) from the real per-category data, so a newly added category
   appears automatically instead of being silently dropped.
2. Make the script fail loudly: track substitution counts per pattern and exit non-zero if any
   pattern matches zero times, and warn if any rule file has no parseable SEVERITY.
3. Hand-edit the "Known gaps" card to state accurately that Learn page statistics are generated
   from the codebase by CI, and name what is still maintained by hand.
4. Update the stale counts in README.md (feature table rows, bracketed playbook count, both
   Mermaid diagram nodes) and state clearly whether that update is now automated or remains a
   manual step.