# Contributing to bf6-portal-mod-types

This document is for **contributors** (building, versioning, docs site). For install and usage, see
[README.md](README.md).

---

## Overview

The official BF6 Portal SDK ships a single `index.d.ts` that declares the global `mod` namespace. That file is large and
includes very large enums, which makes the API harder to consume (for humans and for LLMs/agents) and prone to polluting
editor and tooling context.

This repo:

1. **Splits** the official `mod` namespace `index.d.ts` into a sensible layout under `src/original/`, mirroring the
   structure of the built output (e.g. `enums.d.ts`, `types.d.ts`, `event-handler-signatures.d.ts`,
   `runtime-spawn-enums/*.d.ts`).
2. **Documents** a growing subset of the API in a parallel `documentedMod` namespace under `src/documented/`, with JSDoc
   for parameters, return values, examples, and usage notes—guided by experience with Portal and community feedback.
3. **Builds** by merging that JSDoc into the original types and writing the final `mod` namespace files to the project
   root, with `index.d.ts` as the entry point.
4. **Verifies** that all added JSDoc is present in the build output.
5. **Publishes** the root `.d.ts` files (and `README.md`) to npm; the docs site is built by a GitHub Action on push to
   `master` and deployed to GitHub Pages (the `docs/` directory is not committed).

## Repository layout

| Path                                            | Purpose                                                                                                                                           |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `src/original/`                                 | Split copy of the official Portal `mod` namespace. Mirrors the root output layout.                                                                |
| `src/documented/`                               | `documentedMod` namespace that mirrors `src/original/`. Only files listed here get JSDoc merged in; others are copied as-is.                      |
| `src/merge-docs.js`                             | Build script: for each file in `original/`, merges JSDoc from `documented/` (if present) into the `mod` namespace and writes to the project root. |
| `src/verify-build.js`                           | Verification script: ensures every documented node in `documented/` has matching JSDoc in the root output.                                        |
| `src/common.js`                                 | Shared helpers for the merge and verify scripts.                                                                                                  |
| Root `*.d.ts`, `enums/`, `runtime-spawn-enums/` | **Build output**—the published type definitions. Do not edit by hand; they are generated by `npm run build`.                                      |
| `index.d.ts`                                    | Entry point: triple-slash references to the rest of the `mod` namespace.                                                                          |
| `docs/`                                         | TypeDoc output for the docs site. Generated by `npm run docs` (locally) or by the deploy workflow. Not committed; see "GitHub Pages" below.       |

## Version semantics

The official Portal SDK uses a **four-part** version (e.g. `1.1.3.0`) and does not follow semver. We assume the first
segment will not change (i.e. no "2.x.y.z" release). This package therefore **drops the first segment** and uses
three-part semver:

- **bf6-portal-mod-types** `2.2.0` corresponds to the official **1.2.2.0** `mod` namespace.
- **Patch** releases (e.g. `2.2.1`, `2.2.2`) = same official API, with additional JSDoc or usability improvements only.
- When the Portal team releases a new SDK version (e.g. `1.2.3.0`), this package would move to a new **minor** (e.g.
  `2.3.0`) and the root types would be updated from the new official `index.d.ts`.

## Scripts

| Script             | Description                                                                           |
| ------------------ | ------------------------------------------------------------------------------------- |
| `npm run build`    | Runs `merge-docs.js` and Prettier to produce root `.d.ts` files.                      |
| `npm run verify`   | Runs `verify-build.js` to ensure all `documented/` JSDoc appears in the build output. |
| `npm run docs`     | Runs TypeDoc with `README.md` as the readme and writes the `docs/` directory.         |
| `npm run lint`     | ESLint.                                                                               |
| `npm run prettier` | Format supported files.                                                               |

## Development workflow

1. Update **official** types by replacing the contents of `src/original/` with the new SDK layout (split from the new
   `index.d.ts` as needed).
2. Add or extend JSDoc in **`src/documented/`** using the `documentedMod` namespace; keep structure and names in sync
   with `src/original/` so the merge can match nodes.
3. Run `npm run build` then `npm run verify`. Fix any verify failures (e.g. missing or renamed nodes).
4. Run `npm run docs` locally only if you want to preview the docs; the site is built and deployed by the workflow on
   merge to `master`.
5. Commit the changes to `src/` and the **root** `.d.ts`, then publish.

## Package contents (shipped to npm)

The `package.json` `files` array controls what is published. It includes:

- `index.d.ts` (entry point)
- `enums.d.ts`, `event-handler-signatures.d.ts`, `types.d.ts`
- `enums/`
- `runtime-spawn-enums/`
- `README.md`

Consumers get the global `mod` namespace via the package's `types` field (`index.d.ts`) and configure their project with
`"types": ["bf6-portal-mod-types"]` (and any other type packages) in `tsconfig.json`.

## GitHub Pages (docs site)

The API reference site is **not** committed; it is built and deployed by a GitHub Action whenever changes are pushed to
`master` (including when a PR is merged). It is hosted [here](https://deluca-mike.github.io/bf6-portal-mod-types/). Use
it to browse the `mod` namespace, see which symbols are documented, and copy examples.