@heroiclands/package-build 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,91 @@
 # @heroiclands/package-build
 
+## 0.6.0
+
+### Minor Changes
+
+- 53dd83b: **Commands for the Foundry container and the end-to-end harness** (#18).
+  
+  A package that declares a `compatibility` range is making a promise, and until
+  now exactly one repository could defend it: container lifecycle, world seeding
+  and the browser harness all lived in `SoHL/utils/`, so two of three HeroicLands
+  module repositories declared a range nothing could test.
+  
+  Two new commands:
+  
+  ```
+  package-build container <stage> <start|stop|restart|recreate|rm|status|logs|pull>
+  package-build e2e <seed|run|open|fast|sweep>
+  ```
+  
+  **Nothing about the destination is restated.** A container mounts
+  `FOUNDRYVTT_<STAGE>_DATA` — the variable `deploy` already writes into — so
+  serving what was just deployed is the next step from one variable rather than a
+  second configuration. Stage ports, the container name, the world id and the GM
+  credentials all derive from what the repository already declares.
+  
+  **The end-to-end stage is pinned to `compatibility.minimum`.** The claim and the
+  evidence for it are now literally the same number, so raising the pin is what it
+  should be: a decision to raise the supported floor. `FOUNDRYVTT_<STAGE>_VERSION`
+  still wins for a one-off, and `e2e sweep <build>` runs the full suite against a
+  build the repository does _not_ pin, so `compatibility.verified` can be evidence.
+  
+  **The wait is for an active world, not an open port.** Foundry answers on its
+  port long before a world is serving, and a suite started then fails every spec
+  for no visible reason. A licence failure — which never recovers — is read out of
+  the container log and reported at once.
+  
+  **What the suite _is_ stays the consumer's**, named in `packageBuild.e2e.suite`
+  the way `assetTransform` and `manifestFlags` are named. So does the seed world's
+  extra content, in `packageBuild.e2e.documents`. A **module** package additionally
+  gets `core.moduleConfiguration` seeded, without which its suite would run against
+  a world that never loaded it.
+  
+  New configuration, all optional: `packageBuild.container.{image,stages}` and
+  `packageBuild.e2e.{stage,suite,build,world,gm,documents}`. New subpath exports
+  `./container` and `./e2e`. Adds `@foundryvtt/foundryvtt-cli` as a dependency —
+  seeding a world means compiling its LevelDB collections.
+- 3c631c3: Add the two localization guards that keep a package translated: `lang coverage`
+  and `lang hardcoded` (#19).
+  
+  `lang check` already asked whether a localization file is _shippable_. Neither
+  of the questions that decide whether it is _translated_ was asked anywhere but
+  in the Song of Heroic Lands repository, in two scripts of its own — and both
+  satellites ship `lang/` files with no guard at all.
+  
+  **`lang coverage`** — every key the package references exists, and every key it
+  declares is referenced. The two halves are not the same severity: a referenced
+  key that is missing renders to a player as its own raw key string and fails the
+  run; a declared key nothing references is reported and does not, because no scan
+  sees every way a key is reached and a guard that fails over one teaches people
+  to switch it off.
+  
+  **`lang hardcoded`** — every user-visible literal in the templates goes through
+  localization, and every template still compiles once it does. This is the
+  _reverse_ walk, and it is the reason both exist: coverage walks key → file and
+  is blind to a template that names no key whatsoever. Before the work that
+  prompted this guard, SoHL had 516 hardcoded English literals across 61
+  templates, and translating every key in `en.json` would have left every one of
+  them in English.
+  
+  **What a repository states.** Which files to scan is configuration and defaults
+  to the conventional layout, so a repository that follows it declares nothing.
+  The escape hatches — a key retained despite looking unreferenced, a literal
+  allowed despite looking like prose — each carry a required `reason`, because
+  each is a claim a reviewer has to be able to check.
+  
+  **What stays the repository's.** `packageBuild.lang.references` names a module
+  exporting `references(context) -> ReferenceSet`, contributing the keys only that
+  repository's conventions can find — SoHL's `defineType(prefix, def)` mints one
+  key per member of an enum by a rule of its own. Everything Foundry-shaped is
+  built in: `{{localize}}`, `game.i18n.localize` / `format`, keys in string and
+  template literals, a DataModel's `LOCALIZATION_PREFIXES`, and the field
+  `label` / `hint` keys Foundry mints off one.
+  
+  Scripts are read through the **AST**, so a key named in a JSDoc `@example` is
+  neither required to exist nor able to keep a dead key alive. `typescript` and
+  `handlebars` become runtime dependencies for that reason.
+
 ## 0.5.0
 
 ### Minor Changes

package/README.md

@@ -41,6 +41,14 @@ The whole of assemble → validate → ship, one subpath each:
 - **`lang`** — what a shippable Foundry localization file must satisfy: it
   parses, its top level is an object, no key is both a leaf and a dotted prefix
   of another, placeholders are single-braced, and key segments carry no data.
+- **`coverage`** — whether the keys a package references and the keys it
+  declares are the same set. A referenced key that is missing renders to a
+  player as its own raw key string, so it fails the run; a declared key nothing
+  references is reported and does not.
+- **`templates`** — the opposite question, which coverage cannot ask: whether
+  the markup's user-visible text goes through localization at all, rather than
+  sitting in the file in English — and whether each template still compiles once
+  it does.
 - **`bundle`** — whether the manifest agrees with the file it points at.
   Declared under `"esmodules"` the bundle must parse as a module; declared under
   `"scripts"` it must declare **nothing** at top level, because every top-level
@@ -53,6 +61,12 @@ The whole of assemble → validate → ship, one subpath each:
   a local copy or SFTP. Always a staged, atomic swap: a running Foundry holds
   its LevelDB packs open, and replacing them in place leaves a directory LevelDB
   "repairs" to zero.
+- **`container`** — running what was just deployed. The Foundry data root a
+  deploy writes into is the directory a container mounts, so serving the result
+  is the next step from one variable rather than a second configuration.
+- **`e2e`** — a disposable world, seeded with a Gamemaster whose password is
+  known, served until it is genuinely **active**, and a suite driven against it.
+  What the suite _is_ stays the repository's.
 - **`text`** — locating a literal inside a file, so a finding names the line and
   column it is about.
 
@@ -89,9 +103,40 @@ packageBuild:
 
   lang:
     sources: lang/*.json
-    # Printed after a failure — where this repository documents its key rules.
+    # Printed after a `lang check` failure — where this repository documents its
+    # key rules.
     help: See kb/dev-docs/reference/localization-keys.md.
 
+    # `lang coverage` and `lang hardcoded`. Every one of these defaults to the
+    # conventional layout, so a repository that follows it states none of them.
+    primary: lang/en.json # the file coverage is measured against
+    scripts: src/**/*.{ts,mjs} # scanned for key references
+    templates: templates/**/*.hbs # scanned for references and for English
+
+    # Only when the package references a root its file does not yet declare;
+    # otherwise the roots are read from the file's own keys.
+    keyRoots: [SOHL, TYPES, TYPE]
+
+    # Optional. A module exporting `references(context) -> ReferenceSet`,
+    # contributing the keys only this repository's conventions can find. SoHL's
+    # `defineType(prefix, def)` mints one key per member of an enum by a rule of
+    # its own; no shared guard can know it, and no repository can compare the
+    # result against the file. See "Contributing generated keys" below.
+    references: ./utils/lang-references.mjs
+
+    # Keys reached in a way no scan can see, exempt from the unreferenced
+    # advisory. The reason is required: it is a claim a reviewer has to be able
+    # to check, and the honest fix for an unreferenced key is to delete it.
+    retained:
+      - prefix: SOHL.Gear.Action.
+        reason: Titles built as `${titlePrefix}.${shortcode}` — the prefix is a parameter.
+
+    # Template literals that are deliberately not localization keys. The escape
+    # hatch, not the rule.
+    allow:
+      - literal: item.system.code === 'pyrn'
+        reason: An expression example shown as a placeholder — code, not prose.
+
   deploy:
     # Prefix of the shared SFTP override variables. Default `SOHL`.
     envPrefix: SOHL
@@ -135,6 +180,40 @@ packageBuild:
     socket: true
     grid: { distance: 5, units: ft }
     primaryTokenAttribute: health
+
+  # Running the deployed package in a Foundry container. The four conventional
+  # stages — dev, qa, prod, test — need no entry at all: their data root is
+  # `FOUNDRYVTT_<STAGE>_DATA`, the same variable `deploy` writes into, and their
+  # ports are conventional. Declare a stage only when it is genuinely yours.
+  container:
+    stages:
+      # SoHL keeps the previous, pre-TypeScript system on an older Foundry.
+      # An empty `world` declares "never auto-launch" — it is managed by hand.
+      leg: { port: 30000, world: "", version: "12.331" }
+
+  e2e:
+    # The one thing the harness does not own. Standing Foundry up and seeding a
+    # world is nobody's local problem; what runs against it is entirely yours.
+    suite:
+      run: [npx, cypress, run]
+      open: [npx, cypress, open]
+
+    # What the fast loop can rebuild, in the order it must be built: the
+    # bundler empties the stage, so it goes first. `recreate` marks a target
+    # whose output Foundry reads once, at world launch.
+    build:
+      code: build:code
+      assets: build:assets
+      db: build:db
+      system: { script: build:system, recreate: true }
+
+    # Everything here is optional — it derives from the package id otherwise.
+    world: { id: sohl-e2e, title: SoHL E2E }
+    gm: { name: Gamemaster, password: sohl-e2e }
+
+    # Extra world collections, compiled from directories of JSON documents.
+    documents:
+      actors: cypress/fixtures/actors
 ```
 
 ### The manifest is generated, not stamped
@@ -198,9 +277,13 @@ npx package-build clean [--distclean]
 npx package-build assets
 npx package-build manifest
 npx package-build lang check
+npx package-build lang coverage [--unused]
+npx package-build lang hardcoded
 npx package-build bundle check
 npx package-build release
 npx package-build deploy <stage>
+npx package-build container <stage> <start|stop|restart|recreate|rm|status|logs|pull>
+npx package-build e2e <seed|run|open|fast|sweep>
 ```
 
 Wrapped as npm scripts — SoHL spells them:
@@ -211,9 +294,15 @@ Wrapped as npm scripts — SoHL spells them:
   "distclean": "package-build clean --distclean",
   "build:assets": "package-build assets",
   "lint:lang": "package-build lang check",
+  "lint:lang-coverage": "package-build lang coverage",
+  "lint:lang-hardcoded": "package-build lang hardcoded",
   "lint:bundle-globals": "package-build bundle check",
   "build:pack-release": "package-build release",
-  "push:qa": "package-build deploy qa"
+  "push:qa": "package-build deploy qa",
+  "container:dev": "package-build container dev",
+  "e2e:full": "package-build e2e run",
+  "e2e:fast": "package-build e2e fast",
+  "e2e:sweep": "package-build e2e sweep"
 }
 ```
 
@@ -224,6 +313,46 @@ without renaming the first (`lang check`, `bundle check`). Flat `lang:check`
 names would make every operation a new top-level command and hide which ones
 belong together.
 
+**What the two localization guards ask.** They are deliberate opposites, and
+neither can answer the other's question. `lang coverage` walks _key → file_, so
+it is completely blind to a template that names no key whatsoever; `lang
+hardcoded` walks _text → key_, and catches exactly that. Before the work that
+prompted the second, Song of Heroic Lands had **516 hardcoded English literals
+across 61 templates** — translating every key in `en.json` would have left every
+one of them in English.
+
+**Contributing generated keys.** `packageBuild.lang.references` names a module
+exporting `references(context)`, called once with
+`{ config, rootDir, roots, files }` — `files` being the scanned sources as
+`{ path, text }`, already read, so the contributor sees exactly the text the
+built-in scan saw. It returns a reference set:
+
+```js
+export function references({ files }) {
+  return {
+    keys: [
+      // `exact` when the key is minted whole, so keys sitting beneath it do
+      // not vouch for it; `origin` is the verb phrase the message reads with.
+      {
+        key: "SOHL.Skill.CODE.lore",
+        file: "src/utils/constants.ts",
+        line: 42,
+        exact: true,
+        origin: "defineType generates",
+      },
+    ],
+    namespaces: ["SOHL.Skill.CODE"], // families whose leaves are never named
+    patterns: ["SOHL.Skill.*.label"], // shapes, `*` standing for one segment
+    findings: [], // whatever the contributor could not resolve
+  };
+}
+```
+
+Everything Foundry-shaped is already built in — `{{localize}}`,
+`game.i18n.localize` / `format`, keys in string and template literals, a
+DataModel's `LOCALIZATION_PREFIXES`, the `FIELDS.<field>.label` / `.hint` keys Foundry
+mints off one. A contributor is for what only the repository knows.
+
 **What `bundle check` checks.** Three ways a package builds successfully and
 still does not load, none of which a bundler can see, because each is a
 disagreement between two files rather than a fault in either:
@@ -254,6 +383,113 @@ moved into configuration; the boilerplate lives in the CLI, once.
 `--version` and `--help` answer in a directory with no configuration at all.
 Running an actual command resolves it, and fails loudly when it is missing.
 
+## Standing Foundry up, and running a suite against it
+
+A package that claims a `compatibility` range is making a promise, and a
+promise is only defended if something exercises it. Until now exactly one
+repository could: the container lifecycle, the world seeding and the browser
+harness all lived in `SoHL/utils/`, so two of the three HeroicLands module
+repositories declared a range nothing could test.
+
+**The seam already existed.** `package-build deploy <stage>` installs a staged
+package into `FOUNDRYVTT_<STAGE>_DATA`; a container mounts that same directory
+at `/data` and serves it. Running Foundry against what was just deployed is the
+next step from one variable, not a second configuration — so nothing about the
+destination, the stage, or the package identity is restated.
+
+### Which Foundry build a run pins
+
+`compatibility.minimum` is the oldest Foundry a package claims to run on, and
+that claim is what the suite exists to defend. Testing above the floor tests a
+configuration no user is promised while leaving the promised one unverified: a
+regression that breaks the floor but works on a newer build passes in silence.
+
+So **the end-to-end stage is pinned to `compatibility.minimum` itself**, read
+from the top level of the shared configuration. The claim and the evidence are
+the same number and cannot drift apart, and raising the pin is what it should
+be — a decision to raise the supported floor, made by editing the claim.
+
+`FOUNDRYVTT_<STAGE>_VERSION` still wins, so a contributor can sit on another
+build without touching committed configuration. A floor that names no build
+(`"14"`) cannot pin one; the run floats on the major tag, visibly, rather than
+pretending to a precision it lacks.
+
+### The sweep
+
+Routine runs go against the floor, which leaves the other direction untested: a
+new Foundry release can break a package and nothing notices until a user does.
+
+```
+npx package-build e2e sweep 14.367
+```
+
+That is the full suite — reseeded world and all — against a build the
+repository does not pin. It must be the full path rather than the fast one: a
+seeded world is stamped with the build that created it, and Foundry refuses to
+auto-launch a world stamped by another. It takes the build as an argument and
+has **no default**, because the product of a sweep is a citable result ("the
+full suite passed on 14.367") and "the newest release" is not a constant any
+repository can hold without rotting.
+
+A green sweep is what licenses moving `compatibility.verified` to that build. A
+red one is the early warning the sweep exists to produce.
+
+### Waiting for a world, not for a port
+
+Foundry answers on its port long before a world is serving. A suite started at
+that moment fails every spec for no visible reason, which is the single most
+expensive way an integration harness wastes an afternoon. So the wait is for
+the join screen — the form a world renders only once it is **active** — and a
+licence failure, which never recovers, is read out of the container log and
+reported at once rather than after a three-minute timeout that explains
+nothing.
+
+### The fast loop
+
+```
+npx package-build e2e fast -- --spec cypress/e2e/skill.cy.js
+```
+
+Rebuild what changed, redeploy, cycle the world, wait for it, re-run. It is one
+command because every step of it has a quiet failure mode:
+
+| Step       | What goes wrong by hand                                                                                                             |
+| ---------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| Build      | The container serves the **built** package, not the source tree.                                                                    |
+| Order      | A bundler empties the stage, so building it after the asset and pack passes silently discards them — and the deploy is a mirror.    |
+| Manifest   | Read once at world launch, so it needs a container **recreate**, not a restart. A target declaring `recreate: true` forces one.     |
+| Restart    | A running Foundry holds its packs open, so a content change is invisible until the world reopens them.                              |
+| Stale lock | A container that died holding the data-root lock makes every later boot fail with a message that names no owner.                    |
+| Readiness  | `docker start` returns long before Foundry serves.                                                                                  |
+| The suite  | Editor and agent shells export `ELECTRON_RUN_AS_NODE`, which makes an Electron runner start as plain Node and die on its own flags. |
+
+`--build` takes a comma-separated list of declared targets, `all`, or `none`;
+an unrecognised one fails fast rather than half-deploying. `--recreate` forces
+a recreate, `--no-run` stops once the environment is current, and everything
+else — including anything after a bare `--` — is handed to the suite verbatim.
+
+### What the seeded world holds
+
+A world Foundry will launch without a migration prompt: `world.json`, and one
+Gamemaster whose password is known, so a spec can log in deterministically. It
+also carries one **active** scene, because an empty world auto-starts Foundry's
+welcome tour (whose callout overlays sheets) and a world with no active scene
+has no ready canvas.
+
+For a **module** package it additionally writes `core.moduleConfiguration`,
+switching the module on. A system is the world's own and `world.json` names it;
+a module is not, and without that setting a module repository would stand its
+suite up against a world that never loaded the thing under test.
+
+Anything else — which actors, which journals — is the repository's, declared as
+`packageBuild.e2e.documents` and compiled in beside the built-ins.
+
+The world directory is wiped and rewritten on every seed. That is what makes a
+run repeatable, and it is why `FOUNDRYVTT_<E2E_STAGE>_DATA` must be a separate,
+empty directory: pointing it at a working stage would let the seed delete
+worlds there, and would make the image reuse that stage's `Config/license.json`
+in place of the key dedicated to the suite.
+
 ## Design
 
 **The rules are pure, and I/O is confined to functions named for it.** A rule