@forwardimpact/model 0.5.0 → 0.7.1

package/src/policies/orderings.js

@@ -0,0 +1,312 @@
+/**
+ * Orderings and Comparator Functions
+ *
+ * Canonical orderings for entity types and comparator functions for sorting.
+ *
+ * Naming conventions:
+ * - ORDER_* - canonical ordering arrays
+ * - compareBy* - comparator functions for Array.sort()
+ */
+
+import {
+  getSkillLevelIndex,
+  getBehaviourMaturityIndex,
+  getCapabilityOrder,
+} from "@forwardimpact/schema/levels";
+
+// =============================================================================
+// Canonical Orderings
+// =============================================================================
+
+/**
+ * Skill type ordering (T-shaped profile: core → broad)
+ * Primary skills first, then secondary, broad, and track-added skills.
+ */
+export const ORDER_SKILL_TYPE = ["primary", "secondary", "broad", "track"];
+
+/**
+ * Engineering lifecycle stages in execution order
+ */
+export const ORDER_STAGE = ["specify", "plan", "code", "review", "deploy"];
+
+/**
+ * Agent stage ordering (subset used for agent generation)
+ */
+export const ORDER_AGENT_STAGE = ["plan", "code", "review"];
+
+/**
+ * Stage-to-handoff mapping for checklist derivation
+ *
+ * Maps stage IDs to the stage whose `.ready` criteria should be shown
+ * before leaving that stage.
+ */
+export const CHECKLIST_STAGE_MAP = {
+  plan: "plan",
+  code: "code",
+  review: "review",
+};
+
+// =============================================================================
+// Skill Comparators
+// =============================================================================
+
+/**
+ * Compare skills by level descending (higher level first)
+ * @param {Object} a - First skill entry
+ * @param {Object} b - Second skill entry
+ * @returns {number} Comparison result
+ */
+export function compareByLevelDesc(a, b) {
+  return getSkillLevelIndex(b.level) - getSkillLevelIndex(a.level);
+}
+
+/**
+ * Compare skills by level ascending (lower level first)
+ * @param {Object} a - First skill entry
+ * @param {Object} b - Second skill entry
+ * @returns {number} Comparison result
+ */
+export function compareByLevelAsc(a, b) {
+  return getSkillLevelIndex(a.level) - getSkillLevelIndex(b.level);
+}
+
+/**
+ * Compare skills by type (primary first)
+ * @param {Object} a - First skill entry
+ * @param {Object} b - Second skill entry
+ * @returns {number} Comparison result
+ */
+export function compareByType(a, b) {
+  return ORDER_SKILL_TYPE.indexOf(a.type) - ORDER_SKILL_TYPE.indexOf(b.type);
+}
+
+/**
+ * Compare skills by name alphabetically
+ * @param {Object} a - First skill entry
+ * @param {Object} b - Second skill entry
+ * @returns {number} Comparison result
+ */
+export function compareByName(a, b) {
+  const nameA = a.skillName || a.name;
+  const nameB = b.skillName || b.name;
+  return nameA.localeCompare(nameB);
+}
+
+/**
+ * Compare skills by level (desc), then type (asc), then name (asc)
+ *
+ * Standard priority ordering for skill display:
+ * - Higher levels first
+ * - Within same level, primary before secondary before broad
+ * - Within same type, alphabetical by name
+ *
+ * @param {Object} a - First skill entry
+ * @param {Object} b - Second skill entry
+ * @returns {number} Comparison result
+ */
+export function compareBySkillPriority(a, b) {
+  // Level descending (higher level first)
+  const levelDiff = getSkillLevelIndex(b.level) - getSkillLevelIndex(a.level);
+  if (levelDiff !== 0) return levelDiff;
+
+  // Type ascending (primary first)
+  const typeA = ORDER_SKILL_TYPE.indexOf(a.type);
+  const typeB = ORDER_SKILL_TYPE.indexOf(b.type);
+  if (typeA !== typeB) return typeA - typeB;
+
+  // Name ascending (alphabetical)
+  const nameA = a.skillName || a.name;
+  const nameB = b.skillName || b.name;
+  return nameA.localeCompare(nameB);
+}
+
+/**
+ * Compare skills by type (asc), then name (asc)
+ *
+ * Standard ordering for job skill matrix display:
+ * - Primary skills first, then secondary, then broad, then track
+ * - Within same type, alphabetical by name
+ *
+ * @param {Object} a - First skill entry
+ * @param {Object} b - Second skill entry
+ * @returns {number} Comparison result
+ */
+export function compareByTypeAndName(a, b) {
+  const typeCompare = compareByType(a, b);
+  if (typeCompare !== 0) return typeCompare;
+  return compareByName(a, b);
+}
+
+// =============================================================================
+// Behaviour Comparators
+// =============================================================================
+
+/**
+ * Compare behaviours by maturity descending (higher maturity first)
+ * @param {Object} a - First behaviour entry
+ * @param {Object} b - Second behaviour entry
+ * @returns {number} Comparison result
+ */
+export function compareByMaturityDesc(a, b) {
+  return (
+    getBehaviourMaturityIndex(b.maturity) -
+    getBehaviourMaturityIndex(a.maturity)
+  );
+}
+
+/**
+ * Compare behaviours by maturity ascending (lower maturity first)
+ * @param {Object} a - First behaviour entry
+ * @param {Object} b - Second behaviour entry
+ * @returns {number} Comparison result
+ */
+export function compareByMaturityAsc(a, b) {
+  return (
+    getBehaviourMaturityIndex(a.maturity) -
+    getBehaviourMaturityIndex(b.maturity)
+  );
+}
+
+/**
+ * Compare behaviours by name alphabetically
+ * @param {Object} a - First behaviour entry
+ * @param {Object} b - Second behaviour entry
+ * @returns {number} Comparison result
+ */
+export function compareByBehaviourName(a, b) {
+  const nameA = a.behaviourName || a.name;
+  const nameB = b.behaviourName || b.name;
+  return nameA.localeCompare(nameB);
+}
+
+/**
+ * Compare behaviours by maturity (desc), then name (asc)
+ *
+ * Standard priority ordering for behaviour display:
+ * - Higher maturity first
+ * - Within same maturity, alphabetical by name
+ *
+ * @param {Object} a - First behaviour entry
+ * @param {Object} b - Second behaviour entry
+ * @returns {number} Comparison result
+ */
+export function compareByBehaviourPriority(a, b) {
+  const maturityDiff =
+    getBehaviourMaturityIndex(b.maturity) -
+    getBehaviourMaturityIndex(a.maturity);
+  if (maturityDiff !== 0) return maturityDiff;
+  return compareByBehaviourName(a, b);
+}
+
+// =============================================================================
+// Capability Comparators
+// =============================================================================
+
+/**
+ * Create a comparator for sorting by capability ordinal rank
+ *
+ * The returned comparator uses ordinalRank from loaded capability data,
+ * making the ordering data-driven rather than hardcoded.
+ *
+ * @param {Object[]} capabilities - Loaded capabilities array
+ * @returns {(a: Object, b: Object) => number} Comparator function
+ */
+export function compareByCapability(capabilities) {
+  const order = getCapabilityOrder(capabilities);
+  return (a, b) => {
+    const capA = a.capability || "";
+    const capB = b.capability || "";
+    return order.indexOf(capA) - order.indexOf(capB);
+  };
+}
+
+/**
+ * Sort skills by capability (display order), then by name
+ *
+ * @param {Object[]} skills - Array of skills to sort
+ * @param {Object[]} capabilities - Loaded capabilities array
+ * @returns {Object[]} Sorted array (new array, does not mutate input)
+ */
+export function sortSkillsByCapability(skills, capabilities) {
+  const capabilityComparator = compareByCapability(capabilities);
+  return [...skills].sort((a, b) => {
+    const capCompare = capabilityComparator(a, b);
+    if (capCompare !== 0) return capCompare;
+    const nameA = a.skillName || a.name;
+    const nameB = b.skillName || b.name;
+    return nameA.localeCompare(nameB);
+  });
+}
+
+// =============================================================================
+// Generic Comparator Factory
+// =============================================================================
+
+/**
+ * Create comparator from an ordering array
+ *
+ * @param {string[]} order - Canonical order
+ * @param {(item: Object) => string} accessor - Extract value to compare
+ * @returns {(a: Object, b: Object) => number}
+ */
+export function compareByOrder(order, accessor) {
+  return (a, b) => order.indexOf(accessor(a)) - order.indexOf(accessor(b));
+}
+
+/**
+ * Chain multiple comparators together
+ *
+ * Returns first non-zero result, or 0 if all comparators return 0.
+ *
+ * @param {...Function} comparators - Comparator functions
+ * @returns {(a: Object, b: Object) => number}
+ */
+export function chainComparators(...comparators) {
+  return (a, b) => {
+    for (const comparator of comparators) {
+      const result = comparator(a, b);
+      if (result !== 0) return result;
+    }
+    return 0;
+  };
+}
+
+// =============================================================================
+// Skill Change Comparators (for progression)
+// =============================================================================
+
+/**
+ * Compare skill changes by change magnitude (largest first), then type, then name
+ *
+ * Used for career progression analysis where biggest changes are most important.
+ *
+ * @param {Object} a - First skill change
+ * @param {Object} b - Second skill change
+ * @returns {number} Comparison result
+ */
+export function compareBySkillChange(a, b) {
+  // Change descending (largest improvement first)
+  if (b.change !== a.change) return b.change - a.change;
+
+  // Type ascending (primary first)
+  const typeA = ORDER_SKILL_TYPE.indexOf(a.type);
+  const typeB = ORDER_SKILL_TYPE.indexOf(b.type);
+  if (typeA !== typeB) return typeA - typeB;
+
+  // Name ascending
+  return a.name.localeCompare(b.name);
+}
+
+/**
+ * Compare behaviour changes by change magnitude (largest first), then name
+ *
+ * Used for career progression analysis.
+ *
+ * @param {Object} a - First behaviour change
+ * @param {Object} b - Second behaviour change
+ * @returns {number} Comparison result
+ */
+export function compareByBehaviourChange(a, b) {
+  if (b.change !== a.change) return b.change - a.change;
+  return a.name.localeCompare(b.name);
+}

package/src/policies/predicates.js

@@ -0,0 +1,177 @@
+/**
+ * Entry-Level Predicate Functions
+ *
+ * Pure predicates that operate on single skill/behaviour matrix entries.
+ * Each predicate takes one entry and returns boolean.
+ *
+ * Naming conventions:
+ * - is* - checks a boolean condition
+ * - has* - checks presence of a value
+ * - allOf/anyOf/not - combinators
+ */
+
+import { getSkillLevelIndex } from "@forwardimpact/schema/levels";
+
+// =============================================================================
+// Identity Predicates
+// =============================================================================
+
+/** Always returns true (identity predicate for optional filtering) */
+export const isAny = () => true;
+
+/** Always returns false (null predicate) */
+export const isNone = () => false;
+
+// =============================================================================
+// Human-Only Predicates
+// =============================================================================
+
+/**
+ * Returns true if skill is marked as human-only
+ * @param {Object} entry - Skill matrix entry
+ * @returns {boolean}
+ */
+export const isHumanOnly = (entry) => entry.isHumanOnly === true;
+
+/**
+ * Returns true if skill is NOT human-only (agent-eligible)
+ * @param {Object} entry - Skill matrix entry
+ * @returns {boolean}
+ */
+export const isAgentEligible = (entry) => !entry.isHumanOnly;
+
+// =============================================================================
+// Skill Type Predicates
+// =============================================================================
+
+/**
+ * Returns true if skill type is primary
+ * @param {Object} entry - Skill matrix entry
+ * @returns {boolean}
+ */
+export const isPrimary = (entry) => entry.type === "primary";
+
+/**
+ * Returns true if skill type is secondary
+ * @param {Object} entry - Skill matrix entry
+ * @returns {boolean}
+ */
+export const isSecondary = (entry) => entry.type === "secondary";
+
+/**
+ * Returns true if skill type is broad
+ * @param {Object} entry - Skill matrix entry
+ * @returns {boolean}
+ */
+export const isBroad = (entry) => entry.type === "broad";
+
+/**
+ * Returns true if skill type is track
+ * @param {Object} entry - Skill matrix entry
+ * @returns {boolean}
+ */
+export const isTrack = (entry) => entry.type === "track";
+
+/**
+ * Returns true if skill is primary or secondary (core skills)
+ * @param {Object} entry - Skill matrix entry
+ * @returns {boolean}
+ */
+export const isCore = (entry) =>
+  entry.type === "primary" || entry.type === "secondary";
+
+/**
+ * Returns true if skill is broad or track (supporting skills)
+ * @param {Object} entry - Skill matrix entry
+ * @returns {boolean}
+ */
+export const isSupporting = (entry) =>
+  entry.type === "broad" || entry.type === "track";
+
+// =============================================================================
+// Skill Level Predicates
+// =============================================================================
+
+/**
+ * Create predicate for skills at or above a minimum level
+ * @param {string} minLevel - Minimum skill level
+ * @returns {(entry: Object) => boolean}
+ */
+export function hasMinLevel(minLevel) {
+  const minIndex = getSkillLevelIndex(minLevel);
+  return (entry) => getSkillLevelIndex(entry.level) >= minIndex;
+}
+
+/**
+ * Create predicate for skills at exactly a specific level
+ * @param {string} level - Exact skill level to match
+ * @returns {(entry: Object) => boolean}
+ */
+export function hasLevel(level) {
+  const targetIndex = getSkillLevelIndex(level);
+  return (entry) => getSkillLevelIndex(entry.level) === targetIndex;
+}
+
+/**
+ * Create predicate for skills below a level threshold
+ * @param {string} maxLevel - Level that must NOT be reached
+ * @returns {(entry: Object) => boolean}
+ */
+export function hasBelowLevel(maxLevel) {
+  const maxIndex = getSkillLevelIndex(maxLevel);
+  return (entry) => getSkillLevelIndex(entry.level) < maxIndex;
+}
+
+// =============================================================================
+// Capability Predicates
+// =============================================================================
+
+/**
+ * Create predicate for skills in a specific capability
+ * @param {string} capability - Capability to match
+ * @returns {(entry: Object) => boolean}
+ */
+export function isInCapability(capability) {
+  return (entry) => entry.capability === capability;
+}
+
+/**
+ * Create predicate for skills in any of the specified capabilities
+ * @param {string[]} capabilities - Capabilities to match
+ * @returns {(entry: Object) => boolean}
+ */
+export function isInAnyCapability(capabilities) {
+  const set = new Set(capabilities);
+  return (entry) => set.has(entry.capability);
+}
+
+// =============================================================================
+// Combinators
+// =============================================================================
+
+/**
+ * Compose predicates with AND logic (all must pass)
+ * @param {...Function} predicates - Predicates to combine
+ * @returns {(entry: Object) => boolean}
+ */
+export function allOf(...predicates) {
+  return (entry) => predicates.every((p) => p(entry));
+}
+
+/**
+ * Compose predicates with OR logic (any must pass)
+ * @param {...Function} predicates - Predicates to combine
+ * @returns {(entry: Object) => boolean}
+ */
+export function anyOf(...predicates) {
+  return (entry) => predicates.some((p) => p(entry));
+}
+
+/**
+ * Negate a predicate
+ * @param {Function} predicate - Predicate to negate
+ * @returns {(entry: Object) => boolean}
+ */
+export function not(predicate) {
+  return (entry) => !predicate(entry);
+}