first commit

docs/devtools/tooling/overview/src/tier/tier.md

@@ -0,0 +1,73 @@
+# `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.