@snaptrude/plugin-core 0.9.17 → 0.9.18-edgesetbacks-20261021.1

package/src/api/program/metrics.ts

@@ -1,120 +1,120 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../types"
-
-/**
- * Program metrics — the area-program summary of the active project.
- *
- * Aggregate planning numbers: total target versus allocated area, plus a
- * per-department breakdown. This is the program-mode "am I hitting my area
- * targets?" read; per-entity geometry measurements (a single space's area,
- * volume, bounding box) live under the geometry namespaces, not here.
- *
- * Every area is reported in the summary's `units` (ft² or m²). This is a read:
- * it never throws and returns an empty breakdown with zero totals when the
- * project has no program.
- *
- * Accessed via `snaptrude.program.metrics`.
- */
-export abstract class PluginProgramMetricsApi {
-  constructor() {}
-
-  /**
-   * Get the area-program summary for the active project.
-   *
-   * @returns A {@linkcode PluginProgramMetricsSummary} with project-level totals
-   *   and a per-department area breakdown.
-   *
-   * @examplePrompt How much area have I allocated versus my targets?
-   * @examplePrompt Give me the program area summary
-   * @examplePrompt Which departments are over or under their target area?
-   * @examplePrompt What's the total built area in the program?
-   * @examplePrompt Show the area breakdown per department
-   * @examplePrompt Am I within my area program?
-   *
-   * # Example
-   * ```ts
-   * const m = await snaptrude.program.metrics.get()
-   * console.log(`${m.totalAllocatedArea} / ${m.totalTargetArea} ${m.units}`)
-   * console.log("unassigned:", m.unassignedArea)
-   * for (const d of m.departments) {
-   *   console.log(d.name, d.allocatedArea, d.targetArea)
-   * }
-   * ```
-   */
-  public abstract get(): PluginApiReturn<PluginProgramMetricsSummary>
-}
-
-/**
- * The unit areas are reported in: square feet (`"ft2"`) or square metres (`"m2"`).
- *
- * **Area-units convention (applies to every area-returning method).** A result
- * carries exactly one `units` field, at the **top level of the value the method
- * returns**: on the response **envelope** for `list`/multi/composite results, and
- * on the **record itself** only for a single `.get` that returns a bare record.
- * Inner/leaf records never repeat it.
- */
-export const PluginAreaUnit = z.enum(["ft2", "m2"])
-export type PluginAreaUnit = z.infer<typeof PluginAreaUnit>
-
-/**
- * Per-department area figures within the program summary. Areas are in the
- * enclosing {@linkcode PluginProgramMetricsSummary}'s `units`.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `departmentId` | `string` | Department id |
- * | `name` | `string` | Department name |
- * | `targetArea` | `number \| null` | Target area in project units, or `null` if no target is set |
- * | `allocatedArea` | `number` | Area currently allocated to this department, in project units |
- */
-export const PluginProgramDepartmentMetric = z.object({
-  departmentId: z.string(),
-  name: z.string(),
-  targetArea: z.number().nullable(),
-  allocatedArea: z.number(),
-})
-export type PluginProgramDepartmentMetric = z.infer<
-  typeof PluginProgramDepartmentMetric
->
-
-/**
- * Result of {@linkcode PluginProgramMetricsApi.get}.
- *
- * Reconciliation invariant: `totalAllocatedArea === unassignedArea` plus the sum
- * of every `departments[].allocatedArea`. `totalTargetArea` is the sum of every
- * `departments[].targetArea` (a `null` target counts as 0); unassigned area has
- * no target. Every area is in `units`.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `units` | `"ft2" \| "m2"` | The unit every area in this summary is reported in |
- * | `totalTargetArea` | `number` | Sum of all department target areas |
- * | `totalAllocatedArea` | `number` | Total allocated area = departments + `unassignedArea` |
- * | `unassignedArea` | `number` | Allocated area not attributed to any listed department (site/unassigned) — the delta that reconciles the total |
- * | `departments` | {@linkcode PluginProgramDepartmentMetric}`[]` | Per-department area breakdown |
- */
-export const PluginProgramMetricsSummary = z
-  .object({
-    units: PluginAreaUnit,
-    totalTargetArea: z.number(),
-    totalAllocatedArea: z.number(),
-    unassignedArea: z.number(),
-    departments: z.array(PluginProgramDepartmentMetric),
-  })
-  .refine(
-    (s) => {
-      const summed =
-        s.unassignedArea +
-        s.departments.reduce((acc, d) => acc + d.allocatedArea, 0)
-      // Reconciliation tolerance: 0.01 absolute or 0.01% relative, for float drift.
-      const tolerance = Math.max(0.01, Math.abs(s.totalAllocatedArea) * 1e-4)
-      return Math.abs(s.totalAllocatedArea - summed) <= tolerance
-    },
-    {
-      message:
-        "totalAllocatedArea must equal unassignedArea + the sum of departments[].allocatedArea",
-    },
-  )
-export type PluginProgramMetricsSummary = z.infer<
-  typeof PluginProgramMetricsSummary
->
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+
+/**
+ * Program metrics — the area-program summary of the active project.
+ *
+ * Aggregate planning numbers: total target versus allocated area, plus a
+ * per-department breakdown. This is the program-mode "am I hitting my area
+ * targets?" read; per-entity geometry measurements (a single space's area,
+ * volume, bounding box) live under the geometry namespaces, not here.
+ *
+ * Every area is reported in the summary's `units` (ft² or m²). This is a read:
+ * it never throws and returns an empty breakdown with zero totals when the
+ * project has no program.
+ *
+ * Accessed via `snaptrude.program.metrics`.
+ */
+export abstract class PluginProgramMetricsApi {
+  constructor() {}
+
+  /**
+   * Get the area-program summary for the active project.
+   *
+   * @returns A {@linkcode PluginProgramMetricsSummary} with project-level totals
+   *   and a per-department area breakdown.
+   *
+   * @examplePrompt How much area have I allocated versus my targets?
+   * @examplePrompt Give me the program area summary
+   * @examplePrompt Which departments are over or under their target area?
+   * @examplePrompt What's the total built area in the program?
+   * @examplePrompt Show the area breakdown per department
+   * @examplePrompt Am I within my area program?
+   *
+   * # Example
+   * ```ts
+   * const m = await snaptrude.program.metrics.get()
+   * console.log(`${m.totalAllocatedArea} / ${m.totalTargetArea} ${m.units}`)
+   * console.log("unassigned:", m.unassignedArea)
+   * for (const d of m.departments) {
+   *   console.log(d.name, d.allocatedArea, d.targetArea)
+   * }
+   * ```
+   */
+  public abstract get(): PluginApiReturn<PluginProgramMetricsSummary>
+}
+
+/**
+ * The unit areas are reported in: square feet (`"ft2"`) or square metres (`"m2"`).
+ *
+ * **Area-units convention (applies to every area-returning method).** A result
+ * carries exactly one `units` field, at the **top level of the value the method
+ * returns**: on the response **envelope** for `list`/multi/composite results, and
+ * on the **record itself** only for a single `.get` that returns a bare record.
+ * Inner/leaf records never repeat it.
+ */
+export const PluginAreaUnit = z.enum(["ft2", "m2"])
+export type PluginAreaUnit = z.infer<typeof PluginAreaUnit>
+
+/**
+ * Per-department area figures within the program summary. Areas are in the
+ * enclosing {@linkcode PluginProgramMetricsSummary}'s `units`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `departmentId` | `string` | Department id |
+ * | `name` | `string` | Department name |
+ * | `targetArea` | `number \| null` | Target area in project units, or `null` if no target is set |
+ * | `allocatedArea` | `number` | Area currently allocated to this department, in project units |
+ */
+export const PluginProgramDepartmentMetric = z.object({
+  departmentId: z.string(),
+  name: z.string(),
+  targetArea: z.number().nullable(),
+  allocatedArea: z.number(),
+})
+export type PluginProgramDepartmentMetric = z.infer<
+  typeof PluginProgramDepartmentMetric
+>
+
+/**
+ * Result of {@linkcode PluginProgramMetricsApi.get}.
+ *
+ * Reconciliation invariant: `totalAllocatedArea === unassignedArea` plus the sum
+ * of every `departments[].allocatedArea`. `totalTargetArea` is the sum of every
+ * `departments[].targetArea` (a `null` target counts as 0); unassigned area has
+ * no target. Every area is in `units`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `units` | `"ft2" \| "m2"` | The unit every area in this summary is reported in |
+ * | `totalTargetArea` | `number` | Sum of all department target areas |
+ * | `totalAllocatedArea` | `number` | Total allocated area = departments + `unassignedArea` |
+ * | `unassignedArea` | `number` | Allocated area not attributed to any listed department (site/unassigned) — the delta that reconciles the total |
+ * | `departments` | {@linkcode PluginProgramDepartmentMetric}`[]` | Per-department area breakdown |
+ */
+export const PluginProgramMetricsSummary = z
+  .object({
+    units: PluginAreaUnit,
+    totalTargetArea: z.number(),
+    totalAllocatedArea: z.number(),
+    unassignedArea: z.number(),
+    departments: z.array(PluginProgramDepartmentMetric),
+  })
+  .refine(
+    (s) => {
+      const summed =
+        s.unassignedArea +
+        s.departments.reduce((acc, d) => acc + d.allocatedArea, 0)
+      // Reconciliation tolerance: 0.01 absolute or 0.01% relative, for float drift.
+      const tolerance = Math.max(0.01, Math.abs(s.totalAllocatedArea) * 1e-4)
+      return Math.abs(s.totalAllocatedArea - summed) <= tolerance
+    },
+    {
+      message:
+        "totalAllocatedArea must equal unassignedArea + the sum of departments[].allocatedArea",
+    },
+  )
+export type PluginProgramMetricsSummary = z.infer<
+  typeof PluginProgramMetricsSummary
+>