# `tier/tier.ts`

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

Computes the deterministic `Tier` label for a package given its shortname and
the parsed `package.json` shape. The inference order mirrors
`scripts/folder-reorg/generate-manifest.ts` exactly, so consumers can rely on
the library and the script producing identical tier assignments for the same
input.

The function is pure and synchronous. It takes no side-effects, so it is safe
to call from any tier — including the universal root barrel — even though
some of the dep hints it inspects are Node-only.

## Features

- Six-rung priority cascade — python → r3f → react → browser → server →
  universal
- Exported `SERVER_DEP_HINTS` set for downstream introspection
- Optional `extraHints` parameter merges user-supplied server-tier dep names
  with the built-in set
- Pure / synchronous — zero I/O, zero allocations on the universal fallback
  path beyond the merged-hint set

## Usage: Basic

```ts
import { inferTier } from "@suaveplan/overview";

const tier = inferTier("foo", {
  dependencies: { "node:fs": "*" },
});
// tier === "server"
```

## Usage: Advanced

```ts
import { inferTier, SERVER_DEP_HINTS } from "@suaveplan/overview";

const extra = new Set(["custom-native-binding"]);
const tier = inferTier(
  "thing",
  { dependencies: { "custom-native-binding": "*" } },
  extra,
);

// SERVER_DEP_HINTS exposes the built-in set for tooling that wants to
// surface the rule set in a UI without re-declaring it.
console.log([...SERVER_DEP_HINTS]);
```

The optional third argument is the path for tooling that wants to extend the
hint set (e.g. a project-local native-binding registry) without forking the
library. The base set is read-only and never mutated.

## API Reference

- `inferTier(short: string, pkg: RawPackageJson, extraHints?: ReadonlySet<string>): Tier`
- `const SERVER_DEP_HINTS: ReadonlySet<string>` — eighteen built-in entries
  spanning `node:*` modules and known native bindings

## Implementation Notes

The function performs at most one shallow `Object.keys` pass over each of
`peerDependencies`, `engines`, `dependencies`, and `devDependencies` — O(1)
work per `package.json` in practice. The `mergeHints` helper allocates a new
`Set` only when `extraHints` carries entries; otherwise it returns the base
set unchanged so the common path is allocation-free.