param(
  [string]$Query = "",
  [switch]$All,
  [switch]$Json
)

$Root = Resolve-Path (Join-Path $PSScriptRoot "..")
$RoutingPath = Join-Path $Root "FILES.json"
$Routing = Get-Content -Raw -LiteralPath $RoutingPath | ConvertFrom-Json

$Exact = @{
  ".gitignore" = "ignore rules for local/generated artifacts"
  ".htaccess" = "Apache/static-host cache, MIME, and service-worker behavior"
  "app_manifest.json" = "canonical version plus CSS/JS app shell manifest"
  "favicon.ico" = "legacy favicon"
  "index.html" = "app DOM shell, canvas, panels, dialogs, and ordered script tags"
  "README.md" = "small AI entrypoint and read strategy"
  "AI_MAP.md" = "subsystem map and task-oriented read sets"
  "GAME_FEATURES.md" = "player-facing game features, UI, items, and behavior guide"
  "FILES.json" = "machine-readable file routing and glob semantics"
  "service-worker.js" = "generated offline/cache service worker"
}

$JsExact = @{
  "ants.js" = "ant actor and ant nest worker behavior"
  "assets.js" = "image loading, image metrics, and render caches"
  "audio.js" = "sample playback and audio controls"
  "burn_motion_util.js" = "burning drift and smoke motion helpers"
  "collision_footprint_system.js" = "collision footprint shapes and overlap tests"
  "command_dispatcher.js" = "central command routing for UI/tools/pointers/save"
  "constraint_system.js" = "attachments, ropes, push/pull, and collision constraints"
  "data.js" = "sprite/decor definitions, needs, config, field tuning"
  "debug_tools.js" = "browser debug overlay and diagnostics"
  "disease_registry.js" = "disease definitions and lookup"
  "display_helpers.js" = "shared canvas/display helpers and weather labels"
  "event_bus.js" = "global event bus singleton"
  "family_graph.js" = "lineage graph helpers"
  "geometry_helpers.js" = "shared primitive geometry helpers"
  "ground_types.js" = "ground definitions, multipliers, limits, labels"
  "health.js" = "health, stress, need, damage, and death helpers"
  "history_system.js" = "rolling world statistics/history"
  "impact_core_system.js" = "impact force and hit candidate helpers"
  "input_mode_manager.js" = "pointer/touch/mobile input classification"
  "items.js" = "item constructors, food/grass helpers, item preview drawing"
  "main.js" = "startup, restore, UI binding, update/render loop"
  "math.js" = "shared numeric helpers"
  "mechanical_shape_bridge.js" = "mechanical item shape bridge for world queries"
  "mechanical_system.js" = "mechanical item forces, rails, ropes, pins, fences"
  "perf_profiler.js" = "performance profiler and quality adaptation"
  "registry_base.js" = "registry normalization helper base"
  "render.js" = "main canvas renderer"
  "restore_coordinator.js" = "post-load restore ordering/fixups"
  "sim_core.js" = "simulation primitives and shared helpers"
  "snapshot_system.js" = "world snapshot capture/restore"
  "sound_pack.js" = "logical sound ID to asset mapping"
  "structure_lifecycle.js" = "structure update lifecycle"
  "structures.js" = "structure definitions and placement/runtime helpers"
  "system_order.js" = "named update phase order"
  "text_catalog.js" = "Japanese UI/state/behavior labels"
  "version.js" = "app version/cache/static query config"
  "weather_system.js" = "weather selection and application"
}

function Get-GroupId($Path) {
  foreach ($Group in $Routing.groups) {
    foreach ($Pattern in $Group.patterns) {
      if ($Path -like $Pattern) { return $Group.id }
    }
  }
  return ($Path -split "/")[0]
}

function Get-Meaning($Path) {
  if ($Exact.ContainsKey($Path)) { return $Exact[$Path] }
  if ($Path.StartsWith("js/")) {
    $Name = Split-Path -Leaf $Path
    if ($JsExact.ContainsKey($Name)) { return $JsExact[$Name] }
    if ($Name.StartsWith("world_")) { return "world state/view/update/tool/environment/combat/social subsystem" }
    if ($Name.StartsWith("tarinai_")) { return "creature action/needs/social/item/update subsystem" }
    if ($Name.StartsWith("item_lifecycle_step_")) { return "item lifecycle pipeline stage" }
    if ($Name.StartsWith("item_lifecycle_")) { return "item lifecycle subsystem" }
    if ($Name.StartsWith("item_dynamic_")) { return "dynamic item behavior subsystem" }
    if ($Name.StartsWith("item_")) { return "item registry/runtime/update/render subsystem" }
    if ($Name.StartsWith("simulation_")) { return "simulation phase subsystem" }
    if ($Name.StartsWith("ui_family_")) { return "family tree UI subsystem" }
    if ($Name.StartsWith("ui_input_")) { return "input handling subsystem" }
    if ($Name.StartsWith("ui_")) { return "DOM/panel UI subsystem" }
    if ($Name.StartsWith("save_")) { return "save/load persistence subsystem" }
    if ($Name.StartsWith("physics_")) { return "physics helper/world subsystem" }
    return "runtime JavaScript module"
  }
  if ($Path.StartsWith("scripts/")) { return "repo script/tooling" }
  if ($Path.StartsWith("css/")) { return "stylesheet layer" }
  if ($Path.StartsWith("assets/sprites/")) { return "creature state sprite" }
  if ($Path.StartsWith("assets/ui/")) { return "UI/app/tool image asset" }
  if ($Path.StartsWith("assets/objects/")) { return "field object image asset" }
  if ($Path.StartsWith("assets/sounds/")) { return "voice or sound-effect sample" }
  return "project file"
}

$Files = Get-ChildItem -LiteralPath $Root -Recurse -File -Force |
  Where-Object { $_.FullName -notmatch "\\.git\\" -and $_.FullName -notmatch "\\__pycache__\\" } |
  ForEach-Object { $_.FullName.Substring($Root.Path.Length + 1).Replace("\", "/") } |
  Sort-Object

$Records = foreach ($Path in $Files) {
  $Group = Get-GroupId $Path
  $Meaning = Get-Meaning $Path
  if ($Query -and ($Path.ToLowerInvariant() -notlike "*$($Query.ToLowerInvariant())*" -and $Group.ToLowerInvariant() -notlike "*$($Query.ToLowerInvariant())*" -and $Meaning.ToLowerInvariant() -notlike "*$($Query.ToLowerInvariant())*")) {
    continue
  }
  [pscustomobject]@{ path = $Path; group = $Group; meaning = $Meaning }
}

if ($Json) {
  $Records | ConvertTo-Json -Depth 4
} elseif ($All) {
  $Records | ForEach-Object { "$($_.path): $($_.meaning)" }
} else {
  $Records | Group-Object group | Sort-Object Name | ForEach-Object {
    "$($_.Name): $($_.Count) files"
    $_.Group | Select-Object -ExpandProperty meaning -Unique | Sort-Object | Select-Object -First 8 | ForEach-Object { "  - $_" }
  }
}