You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Generate a human-readable triage report from any data-update commit range: what's new, what changed, and what needs manual follow-up (especially unique mod lines that need {variant:X} tags). Today this triage is done by eyeballing huge generated diffs.
Background (read first)
Read CLAUDE.md. Everything under src/Data/ and src/TreeData/ is largely generated and committed, so every patch update is already a git diff — we just need to summarize it.
The painful manual step this helps with: when a unique item's mod values change between game versions, a maintainer must add {variant:X} tags by hand in src/Export/Uniques/*.lua. A changed mod line on an existing unique in src/Data/Uniques/*.lua is the signal.
A script tools/patch_diff_report.py (Python; this is repo tooling, not runtime code):
Usage:python3 tools/patch_diff_report.py <base-ref> <head-ref> → writes markdown to stdout.
It should run git diff <base>..<head> -- src/Data src/TreeData (use --unified=0 for easier parsing) and produce sections:
New gems — added entries in src/Data/Gems.lua (entries are keyed lines; an added ["Metadata/..."] = { block top-level key = new gem). List name + id.
New/changed skills — files added or modified under src/Data/Skills/, with the granted-effect keys of added blocks.
New uniques — added item blocks in src/Data/Uniques/*.lua (blocks are [[...]] strings; a new block = new unique). List item name (first line of the block).
Changed existing uniques (variant-tag candidates) — blocks present in both versions whose mod lines changed. These are the manual-work items: flag each with the changed lines so a maintainer (or agent) can decide whether {variant} tags are needed in src/Export/Uniques/*.lua.
New crafting mods — added keys in src/Data/ModItem.lua, ModRunes.lua, etc. (counts per file + first 20 ids).
Tree — whether src/TreeData/<latest>/tree.lua changed, plus added/removed node name counts if cheaply extractable (counting added/removed ["dn"]/name fields in the diff is fine; don't parse the whole 2.4 MB tree).
Parsing guidance: work from the diff hunks, not by fully parsing Lua. Keep it simple and resilient — when a section can't be computed, print a one-line warning in the report instead of crashing.
Acceptance criteria
Running against the 0.5 merge example range produces a report that (spot-check) lists "Update Uniques to 0.5" additions and flags changed existing uniques.
Running against a range with no data changes prints a short "no data changes" report and exits 0.
Script has no dependencies beyond the Python 3 standard library + git CLI.
Goal
Generate a human-readable triage report from any data-update commit range: what's new, what changed, and what needs manual follow-up (especially unique mod lines that need
{variant:X}tags). Today this triage is done by eyeballing huge generated diffs.Background (read first)
CLAUDE.md. Everything undersrc/Data/andsrc/TreeData/is largely generated and committed, so every patch update is already a git diff — we just need to summarize it.{variant:X}tags by hand insrc/Export/Uniques/*.lua. A changed mod line on an existing unique insrc/Data/Uniques/*.luais the signal.b804868"Update Uniques to 0.5 (Update Uniques to 0.5 PathOfBuildingCommunity/PathOfBuilding-PoE2#2116)" and8f86373"Add new 0.5 Uniques (Add new 0.5 Uniques PathOfBuildingCommunity/PathOfBuilding-PoE2#2138)").What to build
A script
tools/patch_diff_report.py(Python; this is repo tooling, not runtime code):Usage:
python3 tools/patch_diff_report.py <base-ref> <head-ref>→ writes markdown to stdout.It should run
git diff <base>..<head> -- src/Data src/TreeData(use--unified=0for easier parsing) and produce sections:src/Data/Gems.lua(entries are keyed lines; an added["Metadata/..."] = {block top-level key = new gem). List name + id.src/Data/Skills/, with the granted-effect keys of added blocks.src/Data/Uniques/*.lua(blocks are[[...]]strings; a new block = new unique). List item name (first line of the block).{variant}tags are needed insrc/Export/Uniques/*.lua.src/Data/ModItem.lua,ModRunes.lua, etc. (counts per file + first 20 ids).src/TreeData/<latest>/tree.luachanged, plus added/removed node name counts if cheaply extractable (counting added/removed["dn"]/name fields in the diff is fine; don't parse the whole 2.4 MB tree).audit/*.txtmanifests exist (see Tooling: mod-coverage audit — committed manifest of unsupported mod lines + CI regression guard #67/Tooling: skill stat coverage audit — detect gem stats with no mod mapping #68) and changed in the range, include their added/removed line counts.Parsing guidance: work from the diff hunks, not by fully parsing Lua. Keep it simple and resilient — when a section can't be computed, print a one-line warning in the report instead of crashing.
Acceptance criteria
docs/(e.g.docs/patchUpdates.md, also linking the audit tooling from Tooling: mod-coverage audit — committed manifest of unsupported mod lines + CI regression guard #67/Tooling: skill stat coverage audit — detect gem stats with no mod mapping #68) and linked fromCONTRIBUTING.md's exporter section.Out of scope