Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion 00.config.sh
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
## Path to Closure Compiler
COMPILER="java -jar closure-compiler-v20230103.jar"
COMPILER="java -jar closure-compiler-v20260526.jar"

EXT_NAME=WV
EXT_FILE_NAME="WME_Validator.user.js"
Expand Down
1 change: 1 addition & 0 deletions 99.build.sh
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ cat "${SRC_DIR}/meta/i18n-end.js" >> "${LOC_FILE}"

${COMPILER} \
--language_in ECMASCRIPT_2017 \
--language_out ECMASCRIPT_2017 \
--js "${SRC_DIR}/src/release.js" \
--js "${LOC_FILE}" \
--js "${SRC_DIR}/src/helpers.js" \
Expand Down
112 changes: 112 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What This Is

WME Validator is a Tampermonkey/GreasyFork userscript for the [Waze Map Editor](https://waze.com). It validates map data (segments, nodes, venues) against 150+ rules across 26+ countries, highlights issues in the editor, and generates detailed reports with wiki references and solutions.

## Build Commands

The project uses shell scripts wrapping the Google Closure Compiler (Java). No `npm` or `package.json`.

```bash
./10.release.sh # Release build → build/WME_Validator.user.js (ADVANCED_OPTIMIZATIONS)
./20.debug.sh # Debug build → build/WME_Validator.debug.js (BUNDLE, DEF_DEBUG=true)
./30.gf.sh # GreasyFork build → build/WME_Validator.gf.js (WHITESPACE_ONLY)
./98.format.sh # Format the compiled output with clang-format (Google style, tab width 4)
./99.build.sh # Orchestrator — runs all three build variants
```

Configuration (compiler path, output dirs) is in `./00.config.sh`. The closure compiler binary must be installed; the repo was last tested with v20230103.

There are **no automated tests**. Validation is done manually per `doc/RELENG.md`.

## Architecture

### Build Pipeline

Source files are concatenated in a specific order and fed to Closure Compiler:

1. `meta/meta-begin.js` — UserScript `@userscript` header
2. `meta/i18n-begin.js` — opens the translations object
3. `i18n/default.js` + `i18n/<CC>.js` (26 countries) — localization rules, auto-concatenated
4. `meta/i18n-end.js` — closes the translations object
5. `src/*.js` — core application code
6. `meta/meta-end.js` — closing wrapper
7. `meta/wme-externs.js` + `meta/jquery-1.9.js` — Closure Compiler extern definitions (not bundled, only used for type-checking)

The post-build steps prepend the UserScript metadata header and run `clang-format`.

### Global Namespaces

All runtime state lives in four top-level objects defined in `src/data.js`:

| Namespace | Purpose |
|-----------|---------|
| `_WV` | Private validator state and configuration |
| `_UI` | User interface state |
| `_RT` | Runtime data (current scan results, active segment info) |
| `_REP` | Report accumulator |

The `_THUI` namespace (from `src/lib/thui.js`) is a small embedded HTML UI toolkit.

### Core Execution Flow

```
WME login event
└─ F_LOGIN (src/login.js) — access control, UI initialization

User triggers scan
└─ F_VALIDATE (src/validate.js) — runs all rules against segments/nodes/venues

Map change events (segments/nodes/venues)
└─ F_ONSEGMENTSCHANGED / F_ONNODESCHANGED / F_ONVENUESCHANGED (src/other.js)
└─ re-validates affected objects

User requests report
└─ F_SHOWREPORT (src/report.js) — generates HTML/text/CSV output
```

### Source File Roles

- `src/release.js` — version string, release/expiry dates, CDN URLs, global access lists
- `src/data.js` — namespace definitions, constants, `DEF_DEBUG` flag
- `src/helpers.js` — pure utilities: `classOf`, `deepCopy`, `deepCompare`, `getDirection`
- `src/basic.js` — logging, HTML escaping, Trusted Types policy, error handling
- `src/validate.js` — validation engine; each rule is a function called per object
- `src/report.js` — report rendering (HTML table, plain text, CSV)
- `src/login.js` — login handler, access list parsing, country/user/level gates
- `src/other.js` — WME event listeners and layer change handler
- `src/lib/i18n.js` — i18n lookup helpers
- `src/lib/audio.js` — audio notification system
- `src/lib/thui.js` — tiny UI library for building form controls

### Localization and Country Rules

`i18n/` is a **git submodule** (`https://github.com/WMEValidator/i18n.git`). Each country file (`i18n/AR.js`, `i18n/DE.js`, etc.) overrides or extends the default English rules in `i18n/default.js`. When editing country-specific rules, changes go in the submodule, not in the main repo.

### Access Control

Rules can be gated by user level, username, country, or city using constants from `src/release.js`:
- `GA_FORLEVEL` — minimum WME user level
- `GA_FORUSER` / `GA_FORCOUNTRY` / `GA_FORCITY` — allowlists with negation (`"!Dekis,*"`)

These are evaluated in `F_LOGIN` against `WLM.user` attributes.

### Conventions

- Main handler functions are named `F_ACTION()` (e.g., `F_VALIDATE`, `F_LOGIN`, `F_SHOWREPORT`)
- Constants are `ALL_CAPS`
- JSDoc annotations (`@const`, `@type`, `@suppress`, `@struct`, `@define`) are used throughout — they matter for Closure Compiler's type checker and dead code elimination
- Debug-only code is guarded by `DEF_DEBUG` (a `@define` constant, stripped in release builds)
- All HTML written to the DOM must go through the Trusted Types policy defined in `src/basic.js`

## Release Checklist

See `doc/RELENG.md` for the full checklist. Key steps before releasing:
- Ensure all `window.console` calls are commented out
- Resolve all `TEST:`, `TODO:`, `BETA:` markers
- Verify header fields: country locks, user levels, release date, expiration date
- Run release build and test both in Tampermonkey and Firefox
- Check Unicode characters in the output file
Loading