ranty-js 1.0.0

package/docs/README.md

@@ -0,0 +1,24 @@
+# Ranty.js Docs
+
+The shared product reference for Ranty lives at
+<https://insanityfarm.github.io/ranty/>. The local JS-specific package,
+browser, host-integration, and CLI notes live in [`../README.md`](../README.md).
+
+The authoritative implementation and workflow contract lives in
+[`../spec/README.md`](../spec/README.md). The authoritative terminology
+lives in [`../glossary/README.md`](../glossary/README.md). Future-facing
+follow-up lives in [`../notes.md`](../notes.md).
+
+## Product Docs
+
+- [Hosted Ranty Reference](https://insanityfarm.github.io/ranty/): shared
+  language, stdlib, modules, runtime, and CLI reference
+- [`../README.md`](../README.md): Ranty.js-specific package, browser, Node, and
+  host-integration details
+
+## Workflow Docs
+
+- [`./context-system/README.md`](./context-system/README.md): anti-drift task
+  briefing, locked-subsystem policy, generated artifacts, and review packets
+- [`./repo-workflow/README.md`](./repo-workflow/README.md): repo-wide git and
+  `notes.md` workflow rules

package/docs/context-system/README.md

@@ -0,0 +1,85 @@
+# Context System Guide
+
+This guide covers the anti-drift context system that keeps architecture memory
+compact, queryable, and local to the repository. The implemented behavior still
+lives in [`../../spec/README.md`](../../spec/README.md), and the authoritative
+terminology still lives in [`../../glossary/README.md`](../../glossary/README.md).
+
+## What This System Owns
+
+- task briefing for blank-context sessions
+- subsystem boundaries, invariants, and history anchors
+- locked-subsystem edit policy
+- terminology enforcement based on the glossary source data
+- generated repo topology artifacts for review and exploration
+
+## Start A Task
+
+1. Read `spec/README.md`.
+2. Read `glossary/README.md`.
+3. Run `npm run context:task -- "<task>"`.
+4. Read `.agent-context/active-task.md`.
+5. Follow the listed subsystem records, spec pages, docs, ADRs, and tests before editing.
+
+The active task packet is repo-local and gitignored. `npm run context:check`
+uses it to make sure current work stays inside the planned subsystem surface.
+
+## Locked Subsystems
+
+Locked subsystems are architecture or contract-sensitive seams. They fail
+closed by default.
+
+If a task must edit locked subsystem code:
+
+1. confirm the need to cross that seam
+2. rerun `npm run context:task -- "<task>" --allow-locked=subsystem-id`
+3. update the touched subsystem record and a related ADR in the same change
+
+If the task can stay above the seam, leave the locked subsystem untouched.
+
+## Choose The Right Artifact
+
+Add or update a glossary term when:
+
+- the concept is cross-cutting across multiple subsystems
+- exact wording matters enough that synonym drift would be harmful
+
+Add or update a subsystem invariant when:
+
+- the behavior is architectural or contract-sensitive
+- a future session could accidentally violate it while editing nearby code
+
+Add or update an ADR when:
+
+- the change revises why the system is shaped this way
+- a locked-subsystem policy or architecture decision changed
+- the task needs durable rationale that should survive code churn
+
+Do not stuff subsystem-local jargon into the glossary unless it truly became a
+repo-wide term.
+
+## Generate And Check
+
+- `npm run context:build`: regenerate `glossary/README.md` and files under `spec/generated/`
+- `npm run terms:check`: reject discouraged glossary replacements
+- `npm run arch:check`: enforce import-boundary rules
+- `npm run context:check`: enforce active-task coverage, locked-subsystem policy, and generated-artifact freshness
+- `npm run drift:review`: write `.agent-context/drift-review.md` for a second review session
+
+Treat `context:build` like other derived-artifact generators in the repo: edit
+the source files first, regenerate immediately, then continue with tests or
+follow-up work.
+
+## Review Packet Flow
+
+Run `npm run drift:review` near the end of a task when you want a second review
+session to check for drift. The packet includes:
+
+- the active task summary
+- changed files
+- touched subsystems
+- the invariants that matter most for those subsystems
+- changed authoritative artifacts
+
+The review packet is a bounded summary for reviewers. It is not a second source
+of truth.

package/docs/repo-workflow/README.md

@@ -0,0 +1,40 @@
+# Repository Workflow
+
+This guide covers repo-wide contributor workflow that is not specific to one
+subsystem. The implemented contract still lives in
+[`../../spec/README.md`](../../spec/README.md).
+
+## Git Commits
+
+When a task includes creating a commit:
+
+1. Inspect recent history first with a non-interactive command such as
+   `git log --oneline -n 10`.
+2. Match the commit message tone, structure, and level of detail used by the
+   current repository history.
+3. Prefer non-interactive git commands throughout the workflow.
+4. If both `git add` and `git commit` are part of the task, run them
+   sequentially instead of in parallel so the index lock stays predictable.
+
+Do not treat commit messages as a place to explain implementation details that
+belong in spec pages, ADRs, or subsystem records.
+
+## `notes.md`
+
+[`../../notes.md`](../../notes.md) is intentionally non-authoritative. Use it
+for durable future-facing material such as:
+
+- buildout ideas
+- follow-through reminders
+- open design questions that do not describe current implemented behavior
+
+Do not duplicate current behavior, architecture contracts, or recurring
+workflow instructions in `notes.md`. Those belong in `spec/` or `docs/`.
+
+When a task creates or resolves durable future-facing follow-through:
+
+1. update `notes.md` if the reminder is still useful after the current task
+2. remove entries that are stale, completed, or superseded
+
+If a note becomes part of implemented behavior or a standing workflow, move it
+out of `notes.md` and into the authoritative home.

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "ranty-js",
+  "version": "1.0.0",
+  "description": "Ranty.js - JavaScript port of the Ranty procedural templating language",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/insanityfarm/ranty-js.git"
+  },
+  "homepage": "https://github.com/insanityfarm/ranty-js",
+  "bugs": {
+    "url": "https://github.com/insanityfarm/ranty-js/issues"
+  },
+  "keywords": [
+    "ranty",
+    "templating",
+    "procedural",
+    "generation",
+    "procgen"
+  ],
+  "main": "./dist/ranty.js",
+  "browser": "./dist/ranty.js",
+  "types": "./dist/index.d.ts",
+  "unpkg": "./dist/ranty.js",
+  "jsdelivr": "./dist/ranty.js",
+  "bin": {
+    "ranty-js": "./dist/ranty.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/ranty.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "docs"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "arch:check": "node ./scripts/context-system/architecture.mjs",
+    "bench": "npm run build && bash benchmarks/run-hyperfine.sh",
+    "build": "npm run clean && rollup -c && tsc -p tsconfig.build.json",
+    "check": "npm run lint && npm run format:check && npm run typecheck && npm run test && npm run arch:check && npm run context:check",
+    "clean": "rimraf dist coverage",
+    "context:build": "node ./scripts/context-system/build.mjs",
+    "context:check": "node ./scripts/context-system/check.mjs",
+    "context:task": "node ./scripts/context-system/task.mjs",
+    "dev": "rollup -c -w",
+    "dev:repl": "tsx src/hosts/node/dev-repl.ts",
+    "drift:review": "node ./scripts/context-system/review.mjs",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "npm run lint:eslint && npm run lint:directives && npm run terms:check",
+    "lint:directives": "node ./scripts/check-eslint-directives.mjs",
+    "lint:eslint": "eslint . --max-warnings 0",
+    "lint:fix": "eslint . --fix",
+    "terms:check": "node ./scripts/context-system/terms.mjs",
+    "test": "npm run build && vitest run",
+    "test:unit": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "upstream:check-freshness": "node ./scripts/upstream/check-freshness.mjs",
+    "upstream:sync": "node ./scripts/upstream/sync-ranty.mjs",
+    "verify": "npm run check && npm run build"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.23.0",
+    "@rollup/plugin-commonjs": "^28.0.3",
+    "@rollup/plugin-node-resolve": "^16.0.1",
+    "@types/node": "^22.13.13",
+    "@typescript-eslint/eslint-plugin": "^8.28.0",
+    "@typescript-eslint/parser": "^8.28.0",
+    "eslint": "^9.23.0",
+    "eslint-config-prettier": "^10.1.1",
+    "globals": "^16.0.0",
+    "js-yaml": "^4.1.0",
+    "jsdom": "^26.0.0",
+    "prettier": "^3.5.3",
+    "rimraf": "^6.0.1",
+    "rollup": "^4.36.0",
+    "rollup-plugin-esbuild": "^6.2.1",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2",
+    "vitest": "^3.1.1"
+  }
+}