@org-design-studio/core 0.1.0

package/docs/API.md

@@ -0,0 +1,202 @@
+# `@org-design-studio/core` — API reference
+
+The org-design analytics engine packaged as an embeddable TypeScript library: spans & layers
+diagnostics, data validation and import mapping, a scenario engine with transition-cost-netted
+economics, deterministic insight generation, and a headless org-chart layout. No React, no DOM,
+no storage — the only runtime dependency is `d3-hierarchy`.
+
+- Entry point: a single curated barrel (`src/lib/core.ts` in this repo; `@org-design-studio/core` when published).
+- Build: `npm run build:core` (tsup → `dist-core/` with ESM + CJS + `.d.ts`).
+- Publish manifest template: `packages/core-package.json`.
+
+## Quickstart
+
+```bash
+npm install @org-design-studio/core
+```
+
+```ts
+import {
+  generateDemoData,
+  computeMetrics,
+  generateInsightsFromEmployees,
+  DEFAULT_ASSUMPTIONS,
+} from "@org-design-studio/core";
+
+const employees = generateDemoData(); // or your own Employee[]
+const metrics = computeMetrics(employees, DEFAULT_ASSUMPTIONS);
+const insights = generateInsightsFromEmployees(employees, DEFAULT_ASSUMPTIONS);
+
+console.log(metrics.headcount, metrics.maxLayers, metrics.totalOpportunity);
+console.log(insights[0].title, insights[0].recommendation);
+```
+
+## Methodology guarantees
+
+These hold for every function in the public surface and are covered by the test suite:
+
+1. **Level-aware spans.** Narrow/wide classification uses per-level target bands
+   (`Assumptions.targetSpansByLevel`), not one global threshold. A frontline manager with 6
+   reports and an executive with 6 reports are judged against different bands; flat thresholds
+   (`narrowSpanThreshold`/`wideSpanThreshold`) apply only to unleveled roles.
+2. **Disjoint levers.** The savings opportunities in `OrgMetrics` (delayering, span optimization,
+   duplication) are attributed to disjoint employee sets, so `totalOpportunity` never
+   double-counts a person.
+3. **Transition-cost-netted scenarios.** `evaluateScenario` reports run-rate saving separately
+   from year-1 saving; year-1 is pro-rated by effective month (`year1CapturePct`) and netted
+   against severance/backfill/change cost (`computeTransitionCost`).
+4. **Deterministic.** Same inputs → same outputs. No randomness, network, or clock reads in the
+   analytics path; `generateDemoData()` returns the same ~300-person org every call.
+
+## Modules
+
+### Data model & assumptions (`types`)
+
+| Export | Notes |
+| --- | --- |
+| `Employee` | The canonical input row. Required identity fields plus `level`, `fte`, `salary`, `bonus`, `total_cost`, `status`, org dimensions (`function`, `business_unit`, `location`, …). |
+| `Assumptions` / `DEFAULT_ASSUMPTIONS` | All methodology knobs: span bands per level, target layers, saving percentages, location cost multipliers, transition assumptions, scoring weights. Start from `DEFAULT_ASSUMPTIONS` and spread overrides. |
+| `OrgMetrics`, `OrgHealthScore`, `LayerStat`, `SpanBucket`, `DuplicateRoleGroup` | Output shapes of the analytics module. |
+| `Scenario`, `ScenarioChange`, `ScenarioEvaluation`, `ChangeRisk`, `ScenarioScore` | Scenario engine shapes. `ScenarioChange` is a discriminated union: `move`, `remove_role`, `add_role`, `merge_teams`, `delayer`, `location_shift`, `cost_change`. |
+| `Insight`, `InsightCategory` | Insight output shape (title, narrative, recommendation, impact $, confidence, ease, rank). |
+| `DataQualityReport`, `DataQualityIssue`, `IssueSeverity` | Validation output shapes. |
+| `REQUIRED_FIELDS`, `OPTIONAL_FIELDS`, `FieldMapping` | Canonical field lists for import mapping. |
+| `MONTH_NAMES`, `DEFAULT_TITLE_NOISE_WORDS` | Methodology constants. |
+
+### Hierarchy (`hierarchy`)
+
+- `buildOrgTree(employees): OrgTree` — builds the reporting tree once; computes layer, span,
+  downstream headcount/cost per node, and surfaces `orphans` (manager id not found) and
+  `circular` (reporting cycles) instead of throwing. Every other module consumes this.
+- `subtreeIds(tree, id): string[]` — an employee plus everyone below them.
+- `deepestChains(tree, topN?)` — the longest reporting chains (for layer diagnostics).
+- `wouldCreateCycle(tree, employeeId, newManagerId): boolean` — guard for re-parenting UIs.
+
+### Analytics (`analytics`)
+
+- `computeMetrics(employees, assumptions): OrgMetrics` — the headline call. Headcount/cost
+  rollups by function/BU/location/grade/layer, span buckets, layer stats, manager-of-one and
+  pure-supervisory-layer detection, AI-augmentation exposure, duplicate roles, and the three
+  disjoint savings opportunities plus `orgHealth`.
+- `computeOrgHealth(inputs, assumptions): OrgHealthScore` — explainable 0–100 composite
+  (layer health, span health, manager ratio, management cost, duplication), each component
+  scored and weighted with a plain-language explanation. Already included in
+  `computeMetrics().orgHealth`; exported separately for custom pipelines.
+- `spanBandForLevel(level, assumptions)` / `classifySpan(span, level, assumptions)` — the
+  level-aware span methodology, exposed directly so hosts can render their own span flags.
+- `findDuplicateRoles(employees, assumptions)` / `normalizeTitle(title, noiseWords?)` —
+  duplication analysis with seniority-noise-stripped title normalization.
+- `classifyAiAugmentation(employee, assumptions)` — explicit role-family mapping with a
+  conservative title-keyword fallback; augmentation potential, not an elimination judgement.
+
+### Validation & import (`validation`)
+
+- `validateEmployees(employees): DataQualityReport` — 0–100 quality score with banded verdict
+  and per-issue employee id lists (missing managers, cycles, duplicate ids, cost outliers, …).
+- `autoMapColumns(columns, fields)` — fuzzy-maps a host system's column headers
+  ("Employee ID", "Mgr", "Job Title", …) onto the canonical `Employee` fields.
+- `rowsToEmployees(rows, mapping)` — coerces untyped records into typed `Employee[]` using a
+  `FieldMapping` (numbers parsed, blanks → null manager, sensible defaults).
+
+### Scenario engine (`scenario`)
+
+- `applyChanges(baseline, changes): ApplyResult` — pure function from a baseline plus a list of
+  `ScenarioChange`s to a future-state `Employee[]` (with `warnings` for changes that no longer
+  apply). Never mutates the baseline.
+- `evaluateScenario(baseline, scenario, baselineMetrics, assumptions): ScenarioEvaluation` —
+  full economics: cost/headcount/layer deltas, change risk, weighted score, `runRateSaving`,
+  `transitionCost`, and `netYear1Saving = runRateSaving × year1CapturePct − transitionCost`.
+- `computeTransitionCost(baseline, after, assumptions)` — severance by level band with country
+  multipliers, backfill percentage, and per-move one-time change cost.
+- `year1CapturePct(assumptions)` — share of run-rate captured in year 1 given the effective month.
+- `computeChangeRisk(...)` / `scoreScenario(...)` — the risk and scoring sub-steps, exported for
+  custom dashboards.
+- `diffEmployees(baseline, scenario)` — moved/removed/added/changed sets between two states.
+- `suggestConsolidations(employees, assumptions)` — machine-generated candidate actions
+  (`SuggestedAction[]`) with rationale and indicative saving.
+
+### Insights (`insights`)
+
+- `generateInsightsFromEmployees(employees, assumptions, scenarioEvaluations?)` — convenience:
+  metrics + insights in one call.
+- `generateInsights(ctx: InsightContext)` — same, when you already have `OrgMetrics`.
+- `rankInsights(insights)` — deterministic re-ranking by impact, reach, confidence, and ease;
+  sets `rank` starting at 1.
+
+### Org-chart layout (`org-layout`)
+
+Headless tidy-tree layout over `d3-hierarchy` — returns coordinates only, you render.
+
+- `layoutOrg(tree, rootIds, isExpanded, opts): CanvasLayout` — positioned nodes and edges plus
+  bounds. `FULL_NODE` / `COMPACT_NODE` are ready-made `LayoutOptions`.
+- `elbowPath(x1, y1, x2, y2): string` — SVG path string for an org-chart elbow connector.
+- `fitToBounds(bounds, w, h, …): Viewport` / `zoomAround(vp, x, y, factor, …): Viewport` —
+  viewport math for pan/zoom canvases.
+- `visibleNodes(nodes, vp, w, h, opts, overscan?)` — viewport culling for large orgs.
+
+### Demo data (`demo-data`)
+
+- `generateDemoData(): Employee[]` — deterministic ~300-person company ("Meridian Global
+  Services") with intentional structural issues; useful for demos, tests, and golden files.
+
+### HRIS templates (`hris-templates`)
+
+- `HRIS_TEMPLATES: HrisTemplate[]` — built-in column-name aliases and export instructions for
+  common HRIS exports (Workday, SuccessFactors, …) to seed `autoMapColumns` so a raw system
+  export maps onto the canonical model with little manual work.
+- `getHrisTemplate(id)` — look up a template by its stable id (e.g. `"workday"`).
+
+## Embedding as an add-on module
+
+The intended integration for an HR platform or consultancy toolchain — keep your own UI and
+data store; call the engine on your data:
+
+```ts
+import {
+  autoMapColumns,
+  rowsToEmployees,
+  validateEmployees,
+  computeMetrics,
+  generateInsightsFromEmployees,
+  DEFAULT_ASSUMPTIONS,
+  REQUIRED_FIELDS,
+  OPTIONAL_FIELDS,
+  type Assumptions,
+} from "@org-design-studio/core";
+
+// 1. Map whatever your HRIS export looks like onto the canonical model.
+const columns = Object.keys(rawRows[0]);
+const mapping = autoMapColumns(columns, [...REQUIRED_FIELDS, ...OPTIONAL_FIELDS]);
+const employees = rowsToEmployees(rawRows, mapping);
+
+// 2. Gate on data quality before showing analytics (render report.issues in your UI).
+const report = validateEmployees(employees);
+if (report.band === "Poor") showDataQualityScreen(report);
+
+// 3. Tune the methodology to the client, then compute.
+const assumptions: Assumptions = {
+  ...DEFAULT_ASSUMPTIONS,
+  targetMaxLayers: 6,
+  currency: "EUR",
+  currencySymbol: "€",
+};
+const metrics = computeMetrics(employees, assumptions);
+const insights = generateInsightsFromEmployees(employees, assumptions);
+
+// 4. Render metrics.layerStats, metrics.spanBuckets, metrics.orgHealth,
+//    and the ranked insights with your own components.
+```
+
+Notes for embedders:
+
+- Everything is synchronous and pure — safe in web workers, serverless functions, or the
+  browser. For very large orgs (10k+), run `computeMetrics` off the main thread.
+- The engine never sees the network; data residency is whatever your host app does.
+- Deliberately **not** exported: the app's zustand store and the file/share export module
+  (DOM-dependent). State management and persistence belong to the host.
+
+## Versioning
+
+`0.x`: minors may adjust signatures or methodology constants (changelogged); patches are
+additive/bug-fix only. From `1.0`: any breaking change to an exported symbol or shape is a
+major; new exports and optional fields are minors.

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@org-design-studio/core",
+  "version": "0.1.0",
+  "description": "Org-design analytics engine: spans & layers diagnostics, level-aware span classification, scenario modelling with transition-cost-netted economics, and deterministic insight generation. Pure TypeScript, no UI dependencies.",
+  "license": "MIT",
+  "main": "./dist-core/core.js",
+  "module": "./dist-core/core.mjs",
+  "types": "./dist-core/core.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist-core/core.d.ts",
+      "import": "./dist-core/core.mjs",
+      "require": "./dist-core/core.js"
+    }
+  },
+  "files": [
+    "dist-core",
+    "docs/API.md",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "org-design",
+    "spans-and-layers",
+    "organization",
+    "hr-analytics",
+    "workforce-planning",
+    "scenario-modelling"
+  ],
+  "dependencies": {
+    "d3-hierarchy": "^3.1.2"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}