placementt-core 1.400.968 → 1.400.970

package/lib/index.d.ts

@@ -7,6 +7,7 @@ export * from "./customerCareConfig";
 export * from "./firebase/firebaseConfig";
 export * from "./firebase/firebaseQuery";
 export * from "./typeDefinitions";
+export * from "./skillsResolver";
 export * from "./emailSections";
 export * from "./exportTransformers";
 export * from "./compassExport";

package/lib/index.js

@@ -27,6 +27,7 @@ __exportStar(require("./customerCareConfig"), exports);
 __exportStar(require("./firebase/firebaseConfig"), exports);
 __exportStar(require("./firebase/firebaseQuery"), exports);
 __exportStar(require("./typeDefinitions"), exports);
+__exportStar(require("./skillsResolver"), exports);
 __exportStar(require("./emailSections"), exports);
 __exportStar(require("./exportTransformers"), exports);
 __exportStar(require("./compassExport"), exports);

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;AACA,sDAAoC;AACpC,gEAA8C;AAC9C,0DAAwC;AACxC,2DAAyC;AACzC,kDAAgC;AAChC,uDAAqC;AACrC,4DAA0C;AAC1C,2DAAyC;AAEzC,oDAAkC;AAClC,kDAAgC;AAChC,uDAAqC;AACrC,kDAAgC;AAChC,2DAAyC;AACzC,uDAAqC;AACrC,iDAA+B;AAC/B,8CAA4B;AAC5B,0CAAwB;AACxB,yCAAuB;AACvB,4DAA0C;AAC1C,kDAAgC;AAChC,iDAA+B;AAC/B,2CAAyB;AACzB,4DAA0C;AAC1C,oEAAiD;AACjD,yEAAuD;AACvD,kEAAgD;AAChD,kEAAgD;AAChD,oEAAkD;AAClD,yGAAuF;AACvF,0GAAwF;AACxF,+FAA6E;AAC7E,4DAA0C;AAC1C,oEAAkD;AAClD,gEAA8C;AAC9C,2EAAyD;AACzD,6CAA2B;AAC3B,+CAA6B;AAC7B,6DAAuE;AAA9D,2IAAA,OAAO,OAAuB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;AACA,sDAAoC;AACpC,gEAA8C;AAC9C,0DAAwC;AACxC,2DAAyC;AACzC,kDAAgC;AAChC,uDAAqC;AACrC,4DAA0C;AAC1C,2DAAyC;AAEzC,oDAAkC;AAClC,mDAAiC;AACjC,kDAAgC;AAChC,uDAAqC;AACrC,kDAAgC;AAChC,2DAAyC;AACzC,uDAAqC;AACrC,iDAA+B;AAC/B,8CAA4B;AAC5B,0CAAwB;AACxB,yCAAuB;AACvB,4DAA0C;AAC1C,kDAAgC;AAChC,iDAA+B;AAC/B,2CAAyB;AACzB,4DAA0C;AAC1C,oEAAiD;AACjD,yEAAuD;AACvD,kEAAgD;AAChD,kEAAgD;AAChD,oEAAkD;AAClD,yGAAuF;AACvF,0GAAwF;AACxF,+FAA6E;AAC7E,4DAA0C;AAC1C,oEAAkD;AAClD,gEAA8C;AAC9C,2EAAyD;AACzD,6CAA2B;AAC3B,+CAA6B;AAC7B,6DAAuE;AAA9D,2IAAA,OAAO,OAAuB"}

package/lib/skillsResolver.d.ts

@@ -0,0 +1,41 @@
+import { InstituteData, SkillLabel, SkillsMapping } from "./typeDefinitions";
+/**
+ * Shared resolution of which skills an institute — and a specific student — should see.
+ * Used by the web app (assessment forms, setup, analytics) and the backend (external
+ * parent/employer assessment forms), so keep it dependency-free.
+ *
+ * Model:
+ *  - Institute base set: labels tagged with the institute's skillsFramework, or the
+ *    stored `skills` id list when the framework is "custom".
+ *  - Per-student set: staff-defined skillsMappings rules are evaluated against the
+ *    student's detail fields at view time. Matching rules contribute the union of
+ *    their skills; a student matching no rule gets the full base set.
+ */
+type InstituteSkillsConfig = Pick<InstituteData, "skillsFramework" | "skillsMappings"> & {
+    skills?: string[];
+};
+/** Ids of the institute's base skill set (no student context). */
+export declare function resolveInstituteSkillIds(institute: InstituteSkillsConfig, allLabels: {
+    [id: string]: SkillLabel;
+}): string[];
+/** Does this student's detail fields satisfy a mapping's filters?
+ * Fields are ANDed; values within a field are ORed. An empty rule matches nobody. */
+export declare function studentMatchesSkillsMapping(studentDetails: {
+    [field: string]: unknown;
+} | undefined, filters: SkillsMapping["filters"]): boolean;
+/** Ids of the skills this specific student should be served.
+ * No mappings configured (or no student context) → full base set. */
+export declare function resolveStudentSkillIds(institute: InstituteSkillsConfig, allLabels: {
+    [id: string]: SkillLabel;
+}, studentDetails?: {
+    [field: string]: unknown;
+}): string[];
+/** Convenience: same as resolveStudentSkillIds but returns the label objects keyed by id. */
+export declare function resolveStudentSkills(institute: InstituteSkillsConfig, allLabels: {
+    [id: string]: SkillLabel;
+}, studentDetails?: {
+    [field: string]: unknown;
+}): {
+    [id: string]: SkillLabel;
+};
+export {};

package/lib/skillsResolver.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveInstituteSkillIds = resolveInstituteSkillIds;
+exports.studentMatchesSkillsMapping = studentMatchesSkillsMapping;
+exports.resolveStudentSkillIds = resolveStudentSkillIds;
+exports.resolveStudentSkills = resolveStudentSkills;
+/** Ids of the institute's base skill set (no student context). */
+function resolveInstituteSkillIds(institute, allLabels) {
+    const framework = institute.skillsFramework;
+    if (framework && framework !== "custom") {
+        return Object.entries(allLabels)
+            .filter(([, label]) => label.framework === framework)
+            .map(([id]) => id);
+    }
+    return (institute.skills || []).filter((id) => allLabels[id]);
+}
+/** Does this student's detail fields satisfy a mapping's filters?
+ * Fields are ANDed; values within a field are ORed. An empty rule matches nobody. */
+function studentMatchesSkillsMapping(studentDetails, filters) {
+    const entries = Object.entries(filters || {}).filter(([, values]) => values?.length);
+    if (entries.length === 0)
+        return false;
+    return entries.every(([field, values]) => {
+        const studentValue = String(studentDetails?.[field] ?? "").trim().toLowerCase();
+        return values.some((v) => String(v).trim().toLowerCase() === studentValue);
+    });
+}
+/** Ids of the skills this specific student should be served.
+ * No mappings configured (or no student context) → full base set. */
+function resolveStudentSkillIds(institute, allLabels, studentDetails) {
+    const base = resolveInstituteSkillIds(institute, allLabels);
+    const mappings = institute.skillsMappings || [];
+    if (!studentDetails || mappings.length === 0)
+        return base;
+    const matched = mappings.filter((m) => studentMatchesSkillsMapping(studentDetails, m.filters));
+    if (matched.length === 0)
+        return base;
+    const ids = Array.from(new Set(matched.flatMap((m) => m.skills)))
+        .filter((id) => allLabels[id] && base.includes(id));
+    return ids.length ? ids : base;
+}
+/** Convenience: same as resolveStudentSkillIds but returns the label objects keyed by id. */
+function resolveStudentSkills(institute, allLabels, studentDetails) {
+    return Object.fromEntries(resolveStudentSkillIds(institute, allLabels, studentDetails)
+        .map((id) => [id, allLabels[id]]));
+}
+//# sourceMappingURL=skillsResolver.js.map

package/lib/skillsResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skillsResolver.js","sourceRoot":"","sources":["../src/skillsResolver.ts"],"names":[],"mappings":"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"}

package/lib/typeDefinitions.d.ts

@@ -931,8 +931,16 @@ export type InstituteData = {
     };
     skillsAssessments?: boolean;
     assessActivitySkills?: boolean;
+    /** The framework the institute assesses. When "skillsBuilder"/"sdsMetaskills", the
+     * skill set is resolved dynamically from skillsLabels tagged with that framework —
+     * NOT from a stored id list. When "custom", `skills` holds the selected label ids. */
     skillsFramework?: SkillsFrameworkKey;
+    /** Only meaningful when skillsFramework is "custom": the selected skillsLabels ids
+     * (generic public labels and/or the school's own custom labels). */
     skills: string[];
+    /** Staff-defined rules serving specific skills to specific students based on their
+     * detail fields (studentsFields). Evaluated at assessment view time. */
+    skillsMappings?: SkillsMapping[];
     scheduledSkillsAssessments?: {
         [key in "yearStart" | "yearEnd" | "eachTerm" | "preWorkExperience" | "postWorkExperience" | "employerInteraction"]?: {
             students?: boolean;
@@ -2852,7 +2860,7 @@ export type EmailInteraction = {
      * must NOT set this, or it would escalate recursively. */
     fallback?: ReminderFallbackType;
 };
-/** Skills framework a skill can be tagged against. "custom" is the user's own selection
+/** Skills framework a skill can be tagged against. "custom" is the school's own selection
  * and is never used as a tag on a SkillLabel. */
 export type SkillsFrameworkKey = "custom" | "skillsBuilder" | "sdsMetaskills";
 export type SkillLabel = {
@@ -2860,7 +2868,29 @@ export type SkillLabel = {
     description: string;
     category: keyof typeof skillLabelColours;
     public: boolean;
-    frameworks?: SkillsFrameworkKey[];
+    /** The single framework this label belongs to. Skills on different frameworks are
+     * completely separate documents — duplicates across frameworks are intentional.
+     * Absent for generic/custom labels. */
+    framework?: SkillsFrameworkKey;
+    /** Set when a school created this label as a custom skill (scoped to that school).
+     * Absent for platform-wide labels. */
+    oId?: string;
+};
+/**
+ * A staff-defined rule mapping students to the skills they are served on assessments.
+ * `filters` keys are student detail field names (from InstituteData.studentsFields);
+ * values are the accepted values for that field. A student matches a rule when EVERY
+ * filtered field's value is one of the accepted values (values within a field are OR,
+ * fields are AND). A student matching multiple rules is served the UNION of their
+ * skills. A student matching no rule falls back to the institute's full base set.
+ */
+export type SkillsMapping = {
+    id: string;
+    name?: string;
+    filters: {
+        [field: string]: string[];
+    };
+    skills: string[];
 };
 /** Rater types for skills assessments (mirrors SkillAssessment.userType). */
 export type SkillRater = "students" | "parents" | "employers";
@@ -3479,5 +3509,9 @@ export type LmiStandardsMatchReview = {
         standardLevel: number;
         confidence: number;
     }[];
+    /** Why-it-did-what-it-did counters + samples, for debugging the run. */
+    diagnostics?: {
+        [key: string]: unknown;
+    };
 };
 export {};

package/package.json

@@ -2,7 +2,7 @@
   "private": false,
   "name": "placementt-core",
   "author": "Placementt",
-  "version": "1.400.968",
+  "version": "1.400.970",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "scripts": {

package/src/index.ts

@@ -9,6 +9,7 @@ export * from "./firebase/firebaseConfig";
 export * from "./firebase/firebaseQuery";
 
 export * from "./typeDefinitions";
+export * from "./skillsResolver";
 export * from "./emailSections";
 export * from "./exportTransformers";
 export * from "./compassExport";

package/src/skillsResolver.ts

@@ -0,0 +1,73 @@
+import {InstituteData, SkillLabel, SkillsMapping} from "./typeDefinitions";
+
+/**
+ * Shared resolution of which skills an institute — and a specific student — should see.
+ * Used by the web app (assessment forms, setup, analytics) and the backend (external
+ * parent/employer assessment forms), so keep it dependency-free.
+ *
+ * Model:
+ *  - Institute base set: labels tagged with the institute's skillsFramework, or the
+ *    stored `skills` id list when the framework is "custom".
+ *  - Per-student set: staff-defined skillsMappings rules are evaluated against the
+ *    student's detail fields at view time. Matching rules contribute the union of
+ *    their skills; a student matching no rule gets the full base set.
+ */
+
+type InstituteSkillsConfig = Pick<InstituteData, "skillsFramework" | "skillsMappings"> & {skills?: string[]};
+
+/** Ids of the institute's base skill set (no student context). */
+export function resolveInstituteSkillIds(
+    institute: InstituteSkillsConfig,
+    allLabels: {[id: string]: SkillLabel},
+): string[] {
+    const framework = institute.skillsFramework;
+    if (framework && framework !== "custom") {
+        return Object.entries(allLabels)
+            .filter(([, label]) => label.framework === framework)
+            .map(([id]) => id);
+    }
+    return (institute.skills || []).filter((id) => allLabels[id]);
+}
+
+/** Does this student's detail fields satisfy a mapping's filters?
+ * Fields are ANDed; values within a field are ORed. An empty rule matches nobody. */
+export function studentMatchesSkillsMapping(
+    studentDetails: {[field: string]: unknown} | undefined,
+    filters: SkillsMapping["filters"],
+): boolean {
+    const entries = Object.entries(filters || {}).filter(([, values]) => values?.length);
+    if (entries.length === 0) return false;
+    return entries.every(([field, values]) => {
+        const studentValue = String(studentDetails?.[field] ?? "").trim().toLowerCase();
+        return values.some((v) => String(v).trim().toLowerCase() === studentValue);
+    });
+}
+
+/** Ids of the skills this specific student should be served.
+ * No mappings configured (or no student context) → full base set. */
+export function resolveStudentSkillIds(
+    institute: InstituteSkillsConfig,
+    allLabels: {[id: string]: SkillLabel},
+    studentDetails?: {[field: string]: unknown},
+): string[] {
+    const base = resolveInstituteSkillIds(institute, allLabels);
+    const mappings = institute.skillsMappings || [];
+    if (!studentDetails || mappings.length === 0) return base;
+
+    const matched = mappings.filter((m) => studentMatchesSkillsMapping(studentDetails, m.filters));
+    if (matched.length === 0) return base;
+
+    const ids = Array.from(new Set(matched.flatMap((m) => m.skills)))
+        .filter((id) => allLabels[id] && base.includes(id));
+    return ids.length ? ids : base;
+}
+
+/** Convenience: same as resolveStudentSkillIds but returns the label objects keyed by id. */
+export function resolveStudentSkills(
+    institute: InstituteSkillsConfig,
+    allLabels: {[id: string]: SkillLabel},
+    studentDetails?: {[field: string]: unknown},
+): {[id: string]: SkillLabel} {
+    return Object.fromEntries(resolveStudentSkillIds(institute, allLabels, studentDetails)
+        .map((id) => [id, allLabels[id]]));
+}

package/src/typeDefinitions.ts

@@ -940,8 +940,16 @@ export type InstituteData = {
     // SKILLS ASSESSMENT CONFIGURATION
     skillsAssessments?: boolean,
     assessActivitySkills?: boolean, // ask students to self-assess skills when logging an extracurricular activity
-    skillsFramework?: SkillsFrameworkKey, // which preset the institute started its skill selection from
+    /** The framework the institute assesses. When "skillsBuilder"/"sdsMetaskills", the
+     * skill set is resolved dynamically from skillsLabels tagged with that framework —
+     * NOT from a stored id list. When "custom", `skills` holds the selected label ids. */
+    skillsFramework?: SkillsFrameworkKey,
+    /** Only meaningful when skillsFramework is "custom": the selected skillsLabels ids
+     * (generic public labels and/or the school's own custom labels). */
     skills: string[]
+    /** Staff-defined rules serving specific skills to specific students based on their
+     * detail fields (studentsFields). Evaluated at assessment view time. */
+    skillsMappings?: SkillsMapping[],
     scheduledSkillsAssessments?: {
         [key in "yearStart" | "yearEnd" | "eachTerm" | "preWorkExperience" | "postWorkExperience" | "employerInteraction"]?: {
             students?: boolean,
@@ -2771,7 +2779,7 @@ export type EmailInteraction = {
     fallback?: ReminderFallbackType,
 }
 
-/** Skills framework a skill can be tagged against. "custom" is the user's own selection
+/** Skills framework a skill can be tagged against. "custom" is the school's own selection
  * and is never used as a tag on a SkillLabel. */
 export type SkillsFrameworkKey = "custom" | "skillsBuilder" | "sdsMetaskills";
 
@@ -2780,7 +2788,28 @@ export type SkillLabel = {
     description: string,
     category: keyof typeof skillLabelColours,
     public: boolean,
-    frameworks?: SkillsFrameworkKey[], // which framework presets this skill belongs to
+    /** The single framework this label belongs to. Skills on different frameworks are
+     * completely separate documents — duplicates across frameworks are intentional.
+     * Absent for generic/custom labels. */
+    framework?: SkillsFrameworkKey,
+    /** Set when a school created this label as a custom skill (scoped to that school).
+     * Absent for platform-wide labels. */
+    oId?: string,
+}
+
+/**
+ * A staff-defined rule mapping students to the skills they are served on assessments.
+ * `filters` keys are student detail field names (from InstituteData.studentsFields);
+ * values are the accepted values for that field. A student matches a rule when EVERY
+ * filtered field's value is one of the accepted values (values within a field are OR,
+ * fields are AND). A student matching multiple rules is served the UNION of their
+ * skills. A student matching no rule falls back to the institute's full base set.
+ */
+export type SkillsMapping = {
+    id: string,
+    name?: string,
+    filters: {[field: string]: string[]},
+    skills: string[],
 }
 
 /** Rater types for skills assessments (mirrors SkillAssessment.userType). */
@@ -3447,4 +3476,6 @@ export type LmiStandardsMatchReview = {
         standardLevel: number,
         confidence: number,        // 0-1 heuristic score
     }[],
+    /** Why-it-did-what-it-did counters + samples, for debugging the run. */
+    diagnostics?: {[key: string]: unknown},
 }