@its-not-rocket-science/ananke 0.1.65 → 0.1.66

package/CHANGELOG.md

@@ -6,6 +6,31 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.1.66] — 2026-04-01
+
+### Added
+
+- **PM-7 — API Deprecation Framework (complete):**
+  - `tools/audit-deprecations.ts` (new): scans all `src/` TypeScript files for `@deprecated` JSDoc tags and outputs a structured table of `{ symbol, file, line, since, removeAfter, replacement, overdue }`.
+    - `--json` flag: machine-readable JSON output with timestamp, engine version, and full entry list.
+    - `--check` flag: exits 1 if any symbol's `removeAfter` version ≤ current engine version (overdue).
+  - `prepublishOnly` now includes `npm run audit-deprecations -- --check`: `npm publish` fails if any symbol is overdue for removal.
+  - npm script: `audit-deprecations`.
+  - Structured `@deprecated` convention defined: `@deprecated since {version} — use {replacement} instead. Removes at {removeAfter}.`
+  - All three existing `@deprecated` tags in `src/` updated to the new structured format:
+    - `anankeVersion` in `content-pack.ts`: since 0.1.65, removes at 0.3.0
+    - `Perception` type alias in `sim/ai/perception.ts`: since 0.1.0, removes at 0.3.0
+    - `mkWorld(seed, loadout)` overload in `sim/testing.ts`: since 0.1.0, removes at 0.2.0
+  - `docs/versioning.md`: new "Deprecation lifecycle" section documenting the three-phase pattern (mark → migration window → remove), the required tag format, and the audit checklist.
+  - `docs/module-index.md`: new "Deprecated exports" table surfacing all known deprecated symbols with since/removeAfter/replacement.
+- 0 new tests (5,593 total). Coverage: 97.11%/88.07%/95.83%/97.11%. Build: clean.
+
+### Deprecated
+
+- `AnankePackManifest.anankeVersion` — since 0.1.65, use `registry.compatRange` instead. Removes at 0.3.0.
+
+---
+
 ## [0.1.65] — 2026-04-01
 
 ### Added

package/dist/src/content-pack.d.ts

@@ -1,6 +1,6 @@
 import type { WorldState } from "./sim/world.js";
 /** Current Ananke engine version — used to evaluate pack compatRange at runtime. */
-export declare const ANANKE_ENGINE_VERSION = "0.1.65";
+export declare const ANANKE_ENGINE_VERSION = "0.1.66";
 /** A single actionable validation failure from `validatePack`. */
 export interface PackValidationError {
     /** JSONPath-style location, e.g. `"$.weapons[2].mass_kg"`. */
@@ -81,7 +81,7 @@ export interface AnankePackManifest {
     description?: string;
     /**
      * Minimum Ananke version required, as a semver range string.
-     * @deprecated Use `registry.compatRange` instead — this field is informational only.
+     * @deprecated since 0.1.65 — use `registry.compatRange` instead. Removes at 0.3.0.
      */
     anankeVersion?: string;
     /**

package/dist/src/content-pack.js

@@ -16,7 +16,7 @@ import { registerWorldArchetype, registerWorldItem } from "./world-factory.js";
 // ── Version constant ──────────────────────────────────────────────────────────
 // Must be kept in sync with package.json "version" field.
 /** Current Ananke engine version — used to evaluate pack compatRange at runtime. */
-export const ANANKE_ENGINE_VERSION = "0.1.65";
+export const ANANKE_ENGINE_VERSION = "0.1.66";
 // ── Semver utilities ──────────────────────────────────────────────────────────
 // Lightweight range evaluator — no external dependencies.
 // Supports: >=X.Y.Z  >X.Y.Z  <=X.Y.Z  <X.Y.Z  =X.Y.Z  ^X.Y.Z  ~X.Y.Z

package/dist/src/sim/ai/perception.d.ts

@@ -7,6 +7,6 @@ export interface LocalPerception {
     enemies: Entity[];
     allies: Entity[];
 }
-/** @deprecated Use LocalPerception */
+/** @deprecated since 0.1.0 — use `LocalPerception` instead. Removes at 0.3.0. */
 export type Perception = LocalPerception;
 export declare function perceiveLocal(world: WorldState | undefined, self: Entity, index: WorldIndex, spatial: SpatialIndex, radius_m: number, maxCount?: number, env?: SensoryEnvironment): LocalPerception;

package/dist/src/sim/testing.d.ts

@@ -8,6 +8,6 @@ import { ImpactEvent } from "./events.js";
  */
 export declare function mkHumanoidEntity(id: number, teamId: number, x_m: number, y_m: number, z_m?: number): Entity;
 export declare function mkWorld(seed: number, entities: Entity[]): WorldState;
-/** @deprecated Pass an explicit entity array instead: mkWorld(seed, [a, b]) */
+/** @deprecated since 0.1.0 — use `mkWorld(seed, entities[])` instead. Removes at 0.2.0. */
 export declare function mkWorld(seed: number, loadoutA: Loadout): WorldState;
 export declare function mkImpactEvent(attackerId: number, targetId: number, region?: string, energy_J?: number, protectedByArmour?: boolean, blocked?: boolean, parried?: boolean, weaponId?: string, wpn?: Weapon, hitQuality?: number, shieldBlocked?: boolean): ImpactEvent;

package/docs/versioning.md

@@ -179,3 +179,67 @@ body plan hooks):
 3. Keep an `UPSTREAM.md` at your fork root noting your base version and a diff summary
 4. Periodically rebase onto upstream Tier 3 commits to collect non-breaking improvements;
    treat Tier 1/2 commits as explicit migration tasks to schedule
+
+---
+
+## Deprecation lifecycle
+
+Symbols are deprecated rather than removed immediately so downstream projects have time
+to migrate.  The lifecycle follows a three-phase pattern:
+
+### 1 — Mark deprecated (current version)
+
+Add a structured JSDoc tag to the symbol:
+
+```typescript
+/**
+ * @deprecated since 0.1.50 — use `newFunction` instead. Removes at 0.3.0.
+ */
+export function oldFunction() { … }
+```
+
+The **required format** is:
+
+```
+@deprecated since {version} — use {replacement} instead. Removes at {removeAfter}.
+```
+
+| Field | Meaning |
+|-------|---------|
+| `since` | Version in which the deprecation was introduced |
+| `replacement` | Short description or code reference of what to use instead |
+| `removeAfter` | Version at which the symbol will be deleted — must be a future version |
+
+`removeAfter` must satisfy `> current` at publish time; `npm publish` runs
+`audit-deprecations --check` and fails if any symbol is overdue.
+
+### 2 — Migration window
+
+During the migration window the symbol still works but emits a TypeScript deprecation
+warning in IDEs (the `@deprecated` tag triggers the strikethrough).
+
+The migration window is at least one **minor** version for Tier 2 symbols
+and at least one **major** version for Tier 1 (Stable) symbols.
+
+### 3 — Remove at removeAfter
+
+When the engine reaches `removeAfter`, the symbol is deleted and a CHANGELOG entry is
+added under a `### Removed` heading.  The `since` version and the replacement are
+included in the removal note so the changelog is self-contained.
+
+### Auditing
+
+```bash
+npm run audit-deprecations             # human-readable table
+npm run audit-deprecations -- --json   # machine-readable JSON
+npm run audit-deprecations -- --check  # exit 1 if any overdue
+```
+
+The `--check` flag is run automatically by `npm run prepublishOnly`.
+
+### Adding a new deprecation (checklist)
+
+- [ ] Add the structured `@deprecated` JSDoc tag with `since`, replacement, and `removeAfter`.
+- [ ] Run `npm run audit-deprecations` to confirm the tag is detected and not overdue.
+- [ ] Add a CHANGELOG entry under `### Deprecated`.
+- [ ] Surface the replacement in the relevant `docs/` file or `STABLE_API.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@its-not-rocket-science/ananke",
-  "version": "0.1.65",
+  "version": "0.1.66",
   "type": "module",
   "description": "Deterministic lockstep-friendly SI-units RPG/physics core (fixed-point TS)",
   "license": "MIT",
@@ -247,7 +247,7 @@
     "game-engine"
   ],
   "scripts": {
-    "prepublishOnly": "npm run build && npm run test:coverage",
+    "prepublishOnly": "npm run build && npm run test:coverage && npm run audit-deprecations -- --check",
     "build": "tsc -p tsconfig.build.json",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -298,6 +298,7 @@
     "benchmark-check": "node dist/tools/benchmark-check.js",
     "benchmark-check:strict": "node dist/tools/benchmark-check.js --threshold=0.10",
     "benchmark-check:update": "node dist/tools/benchmark-check.js --update-baseline",
+    "audit-deprecations": "node dist/tools/audit-deprecations.js",
     "benchmark:guide": "node dist/tools/benchmark-guide.js",
     "benchmark:parallel": "node dist/tools/benchmark-parallel.js",
     "run:renderer-bridge": "node dist/tools/renderer-bridge.js",