@forwardimpact/pathway 0.21.0 → 0.22.0

package/src/formatters/progress/shared.js

@@ -11,31 +11,31 @@ import {
 import {
   analyzeProgression,
   analyzeCustomProgression,
-  getNextGrade,
+  getNextLevel,
 } from "@forwardimpact/libpathway/progression";
 import { getOrCreateJob } from "@forwardimpact/libpathway/job-cache";
 
 /**
- * Get the next grade for progression
- * @param {Object} currentGrade
- * @param {Array} grades
+ * Get the next level for progression
+ * @param {Object} currentLevel
+ * @param {Array} levels
  * @returns {Object|null}
  */
-export function getDefaultTargetGrade(currentGrade, grades) {
-  return getNextGrade(currentGrade, grades);
+export function getDefaultTargetLevel(currentLevel, levels) {
+  return getNextLevel(currentLevel, levels);
 }
 
 /**
  * Check if a job combination is valid
  * @param {Object} params
  * @param {Object} params.discipline
- * @param {Object} params.grade
+ * @param {Object} params.level
  * @param {Object} params.track
- * @param {Array} [params.grades] - All grades for validation
+ * @param {Array} [params.levels] - All levels for validation
  * @returns {boolean}
  */
-export function isValidCombination({ discipline, grade, track, grades }) {
-  return isValidJobCombination({ discipline, grade, track, grades });
+export function isValidCombination({ discipline, level, track, levels }) {
+  return isValidJobCombination({ discipline, level, track, levels });
 }
 
 /**
@@ -52,7 +52,7 @@ export function isValidCombination({ discipline, grade, track, grades }) {
  * Prepare current job summary for progress detail page
  * @param {Object} params
  * @param {Object} params.discipline
- * @param {Object} params.grade
+ * @param {Object} params.level
  * @param {Object} params.track
  * @param {Array} params.skills
  * @param {Array} params.behaviours
@@ -61,17 +61,17 @@ export function isValidCombination({ discipline, grade, track, grades }) {
  */
 export function prepareCurrentJob({
   discipline,
-  grade,
+  level,
   track,
   skills,
   behaviours,
   capabilities,
 }) {
-  if (!discipline || !grade) return null;
+  if (!discipline || !level) return null;
 
   const job = getOrCreateJob({
     discipline,
-    grade,
+    level,
     track,
     skills,
     behaviours,
@@ -96,7 +96,7 @@ export function prepareCurrentJob({
  * @property {boolean} isValid
  * @property {string|null} title
  * @property {string|null} invalidReason
- * @property {Object|null} nextGrade
+ * @property {Object|null} nextLevel
  * @property {Array} validTracks - Other valid tracks for comparison
  */
 
@@ -104,35 +104,35 @@ export function prepareCurrentJob({
  * Prepare career progress builder preview for form validation
  * @param {Object} params
  * @param {Object|null} params.discipline
- * @param {Object|null} params.grade
+ * @param {Object|null} params.level
  * @param {Object|null} params.track
- * @param {Array} params.grades - All grades
+ * @param {Array} params.levels - All levels
  * @param {Array} params.tracks - All tracks
  * @returns {CareerProgressPreview}
  */
 export function prepareCareerProgressPreview({
   discipline,
-  grade,
+  level,
   track,
-  grades,
+  levels,
   tracks,
 }) {
   // Track is optional (null = generalist)
-  if (!discipline || !grade) {
+  if (!discipline || !level) {
     return {
       isValid: false,
       title: null,
       invalidReason: null,
-      nextGrade: null,
+      nextLevel: null,
       validTracks: [],
     };
   }
 
   const validCombination = isValidJobCombination({
     discipline,
-    grade,
+    level,
     track,
-    grades,
+    levels,
   });
 
   if (!validCombination) {
@@ -143,27 +143,27 @@ export function prepareCareerProgressPreview({
       isValid: false,
       title: null,
       invalidReason: reason,
-      nextGrade: null,
+      nextLevel: null,
       validTracks: [],
     };
   }
 
-  const title = generateJobTitle(discipline, grade, track);
-  const nextGrade = getNextGrade(grade, grades);
+  const title = generateJobTitle(discipline, level, track);
+  const nextLevel = getNextLevel(level, levels);
 
   // Find other valid tracks for comparison (exclude current track if any)
   const validTracks = tracks.filter(
     (t) =>
       (!track || t.id !== track.id) &&
-      isValidJobCombination({ discipline, grade, track: t, grades }),
+      isValidJobCombination({ discipline, level, track: t, levels }),
   );
 
   return {
     isValid: true,
     title,
     invalidReason: null,
-    nextGrade: nextGrade
-      ? { id: nextGrade.id, name: nextGrade.managementTitle }
+    nextLevel: nextLevel
+      ? { id: nextLevel.id, name: nextLevel.managementTitle }
       : null,
     validTracks: validTracks.map((t) => ({ id: t.id, name: t.name })),
   };
@@ -184,10 +184,10 @@ export function prepareCareerProgressPreview({
  * Prepare career progression between two roles
  * @param {Object} params
  * @param {Object} params.fromDiscipline
- * @param {Object} params.fromGrade
+ * @param {Object} params.fromLevel
  * @param {Object} params.fromTrack
  * @param {Object} params.toDiscipline
- * @param {Object} params.toGrade
+ * @param {Object} params.toLevel
  * @param {Object} params.toTrack
  * @param {Array} params.skills
  * @param {Array} params.behaviours
@@ -196,22 +196,22 @@ export function prepareCareerProgressPreview({
  */
 export function prepareProgressDetail({
   fromDiscipline,
-  fromGrade,
+  fromLevel,
   fromTrack,
   toDiscipline,
-  toGrade,
+  toLevel,
   toTrack,
   skills,
   behaviours,
   capabilities,
 }) {
   // Track is optional (null = generalist)
-  if (!fromDiscipline || !fromGrade) return null;
-  if (!toDiscipline || !toGrade) return null;
+  if (!fromDiscipline || !fromLevel) return null;
+  if (!toDiscipline || !toLevel) return null;
 
   const fromJob = getOrCreateJob({
     discipline: fromDiscipline,
-    grade: fromGrade,
+    level: fromLevel,
     track: fromTrack,
     skills,
     behaviours,
@@ -220,7 +220,7 @@ export function prepareProgressDetail({
 
   const toJob = getOrCreateJob({
     discipline: toDiscipline,
-    grade: toGrade,
+    level: toLevel,
     track: toTrack,
     skills,
     behaviours,
@@ -238,7 +238,7 @@ export function prepareProgressDetail({
     type: s.type,
     fromLevel: s.currentLevel,
     toLevel: s.targetLevel,
-    levelChange: s.change,
+    proficiencyChange: s.change,
   }));
 
   // Transform behaviour changes
@@ -251,12 +251,12 @@ export function prepareProgressDetail({
   }));
 
   const summary = {
-    skillsToImprove: skillChanges.filter((s) => s.levelChange > 0).length,
+    skillsToImprove: skillChanges.filter((s) => s.proficiencyChange > 0).length,
     behavioursToImprove: behaviourChanges.filter((b) => b.maturityChange > 0)
       .length,
     newSkills: skillChanges.filter((s) => !s.fromLevel && s.toLevel).length,
     totalChanges:
-      skillChanges.filter((s) => s.levelChange !== 0).length +
+      skillChanges.filter((s) => s.proficiencyChange !== 0).length +
       behaviourChanges.filter((b) => b.maturityChange !== 0).length,
   };
 
@@ -265,12 +265,12 @@ export function prepareProgressDetail({
     toTitle: toJob.title,
     fromJob: {
       disciplineId: fromDiscipline.id,
-      gradeId: fromGrade.id,
+      levelId: fromLevel.id,
       trackId: fromTrack?.id || null,
     },
     toJob: {
       disciplineId: toDiscipline.id,
-      gradeId: toGrade.id,
+      levelId: toLevel.id,
       trackId: toTrack?.id || null,
     },
     skillChanges,
@@ -292,10 +292,10 @@ export function prepareProgressDetail({
  * Prepare custom progression analysis between any two roles
  * @param {Object} params
  * @param {Object} params.discipline - Current discipline
- * @param {Object} params.currentGrade
+ * @param {Object} params.currentLevel
  * @param {Object} params.currentTrack
  * @param {Object} params.targetDiscipline
- * @param {Object} params.targetGrade
+ * @param {Object} params.targetLevel
  * @param {Object} params.targetTrack
  * @param {Array} params.skills
  * @param {Array} params.behaviours
@@ -303,20 +303,20 @@ export function prepareProgressDetail({
  */
 export function prepareCustomProgression({
   discipline,
-  currentGrade,
+  currentLevel,
   currentTrack,
   targetDiscipline,
-  targetGrade,
+  targetLevel,
   targetTrack,
   skills,
   behaviours,
 }) {
   const analysis = analyzeCustomProgression({
     discipline,
-    currentGrade,
+    currentLevel,
     currentTrack,
     targetDiscipline,
-    targetGrade,
+    targetLevel,
     targetTrack,
     skills,
     behaviours,

package/src/formatters/questions/markdown.js

@@ -4,7 +4,7 @@
  * Formats questions for terminal output as tables and lists.
  */
 
-import { SKILL_LEVELS, BEHAVIOUR_MATURITIES } from "./shared.js";
+import { SKILL_PROFICIENCIES, BEHAVIOUR_MATURITIES } from "./shared.js";
 
 /**
  * Level abbreviations for compact display
@@ -67,7 +67,7 @@ function formatStats(view, skills) {
   // Header
   const skillHeader =
     pad("Skill", 30) +
-    SKILL_LEVELS.map((l) => pad(LEVEL_ABBREVS[l], 7)).join("") +
+    SKILL_PROFICIENCIES.map((l) => pad(LEVEL_ABBREVS[l], 7)).join("") +
     "TOTAL";
   lines.push(skillHeader);
   lines.push("─".repeat(75));
@@ -84,7 +84,7 @@ function formatStats(view, skills) {
 
     const row =
       pad(name, 30) +
-      SKILL_LEVELS.map((l) => {
+      SKILL_PROFICIENCIES.map((l) => {
         const count = skillData[l] || 0;
         levelTotals[l] = (levelTotals[l] || 0) + count;
         return pad(String(count), 7);
@@ -98,7 +98,9 @@ function formatStats(view, skills) {
   lines.push("─".repeat(75));
   const totalsRow =
     pad("TOTAL", 30) +
-    SKILL_LEVELS.map((l) => pad(String(levelTotals[l] || 0), 7)).join("") +
+    SKILL_PROFICIENCIES.map((l) => pad(String(levelTotals[l] || 0), 7)).join(
+      "",
+    ) +
     String(skillTotal);
   lines.push(totalsRow);
   lines.push("");
@@ -150,7 +152,7 @@ function formatStats(view, skills) {
   const gaps = [];
   for (const skillId of sortedSkillIds) {
     const skillData = stats.skillStats[skillId];
-    for (const level of SKILL_LEVELS) {
+    for (const level of SKILL_PROFICIENCIES) {
       if ((skillData[level] || 0) < 1) {
         gaps.push(`${skillId}: missing ${level} questions`);
       }
@@ -250,7 +252,7 @@ function formatSingleSource(view) {
   }
 
   const orderedLevels =
-    sourceType === "skill" ? SKILL_LEVELS : BEHAVIOUR_MATURITIES;
+    sourceType === "skill" ? SKILL_PROFICIENCIES : BEHAVIOUR_MATURITIES;
 
   for (const level of orderedLevels) {
     if (!byLevel[level]) continue;

package/src/formatters/questions/shared.js

@@ -5,9 +5,9 @@
  */
 
 /**
- * Skill levels in order
+ * Skill proficiencies in order
  */
-export const SKILL_LEVELS = [
+export const SKILL_PROFICIENCIES = [
   "awareness",
   "foundational",
   "working",
@@ -28,7 +28,7 @@ export const BEHAVIOUR_MATURITIES = [
 
 /**
  * @typedef {Object} QuestionsFilter
- * @property {string|null} level - Skill level filter
+ * @property {string|null} level - Skill proficiency filter
  * @property {string|null} maturity - Behaviour maturity filter
  * @property {string[]|null} skills - Skill IDs to include
  * @property {string[]|null} behaviours - Behaviour IDs to include
@@ -40,7 +40,7 @@ export const BEHAVIOUR_MATURITIES = [
  * @property {string} source - Source skill/behaviour ID
  * @property {string} sourceName - Source skill/behaviour name
  * @property {string} sourceType - 'skill' or 'behaviour'
- * @property {string} level - Skill level or behaviour maturity
+ * @property {string} level - Skill proficiency or behaviour maturity
  * @property {string} id - Question ID
  * @property {string} text - Question text
  * @property {string[]} lookingFor - Expected answer indicators
@@ -124,7 +124,7 @@ export function flattenQuestions(questionBank, skills, behaviours, filter) {
 
   // Process skill questions
   for (const [skillId, roleTypes] of Object.entries(
-    questionBank.skillLevels || {},
+    questionBank.skillProficiencies || {},
   )) {
     const skillName = getSkillName(skillId, skills);
     const capability = getSkillCapability(skillId, skills);
@@ -218,10 +218,10 @@ export function calculateStats(questions, questionBank) {
   // Calculate full stats for skills and behaviours
   const skillStats = {};
   for (const [skillId, roleTypes] of Object.entries(
-    questionBank.skillLevels || {},
+    questionBank.skillProficiencies || {},
   )) {
     skillStats[skillId] = {};
-    for (const level of SKILL_LEVELS) {
+    for (const level of SKILL_PROFICIENCIES) {
       let count = 0;
       for (const roleType of ROLE_TYPES) {
         count += (roleTypes[roleType]?.[level] || []).length;

package/src/formatters/skill/dom.js

@@ -20,7 +20,7 @@ import { createBackLink } from "../../components/nav.js";
 import { createLevelCell } from "../../components/detail.js";
 import { createSkillFileViewer } from "../../components/skill-file-viewer.js";
 import { createToolIcon } from "../../lib/card-mappers.js";
-import { SKILL_LEVEL_ORDER } from "@forwardimpact/map/levels";
+import { SKILL_PROFICIENCY_ORDER } from "@forwardimpact/map/levels";
 import { prepareSkillDetail } from "./shared.js";
 import { createJsonLdScript, skillToJsonLd } from "../json-ld.js";
 
@@ -97,11 +97,11 @@ export function skillToDOM(
         thead({}, tr({}, th({}, "Level"), th({}, "Description"))),
         tbody(
           {},
-          ...SKILL_LEVEL_ORDER.map((level, index) => {
-            const description = view.levelDescriptions[level] || "—";
+          ...SKILL_PROFICIENCY_ORDER.map((level, index) => {
+            const description = view.proficiencyDescriptions[level] || "—";
             return tr(
               {},
-              createLevelCell(index + 1, SKILL_LEVEL_ORDER.length, level),
+              createLevelCell(index + 1, SKILL_PROFICIENCY_ORDER.length, level),
               td({}, description),
             );
           }),

package/src/formatters/skill/markdown.js

@@ -71,7 +71,7 @@ export function skillToMarkdown(
 
   // Level descriptions table
   lines.push("## Level Descriptions", "");
-  const levelRows = Object.entries(view.levelDescriptions).map(
+  const levelRows = Object.entries(view.proficiencyDescriptions).map(
     ([level, desc]) => [capitalize(level), desc],
   );
   lines.push(tableToMarkdown(["Level", "Description"], levelRows));

package/src/formatters/skill/microdata.js

@@ -87,8 +87,8 @@ export function skillToMicrodata(
 ${metaTag("isHumanOnly", "true")}`);
   }
 
-  // Level descriptions - uses LevelDescriptions itemtype
-  const levelPairs = Object.entries(view.levelDescriptions).map(
+  // Level descriptions - uses ProficiencyDescriptions itemtype
+  const levelPairs = Object.entries(view.proficiencyDescriptions).map(
     ([level, desc]) => ({
       term: formatLevelName(level),
       definition: desc,
@@ -98,7 +98,7 @@ ${metaTag("isHumanOnly", "true")}`);
   sections.push(
     section(
       "Level Descriptions",
-      `${openTag("div", { itemtype: "LevelDescriptions", itemprop: "levelDescriptions" })}
+      `${openTag("div", { itemtype: "ProficiencyDescriptions", itemprop: "proficiencyDescriptions" })}
 ${dl(levelPairs)}
 </div>`,
       2,

package/src/formatters/skill/shared.js

@@ -69,7 +69,7 @@ export function prepareSkillsList(
  * @property {string} capabilityName
  * @property {boolean} isHumanOnly
  * @property {string} capabilityEmoji
- * @property {Object<string, string>} levelDescriptions
+ * @property {Object<string, string>} proficiencyDescriptions
  * @property {Array<{id: string, name: string, skillType: string}>} relatedDisciplines
  * @property {Array<{id: string, name: string, modifier: number}>} relatedTracks
  * @property {Array<{id: string, name: string}>} relatedDrivers
@@ -124,7 +124,7 @@ export function prepareSkillDetail(
     capabilityName: capabilityEntity?.name || skill.capability,
     isHumanOnly: skill.isHumanOnly || false,
     capabilityEmoji: getCapabilityEmoji(capabilities, skill.capability),
-    levelDescriptions: skill.levelDescriptions,
+    proficiencyDescriptions: skill.proficiencyDescriptions,
     relatedDisciplines,
     relatedTracks,
     relatedDrivers,

package/src/handout-main.js

@@ -7,7 +7,7 @@
  *   /driver - All driver slides
  *   /skill - All skill slides
  *   /behaviour - All behaviour slides
- *   /job - All discipline, track, and grade slides
+ *   /job - All discipline, track, and level slides
  */
 
 import { setData, getState } from "./lib/state.js";
@@ -33,7 +33,7 @@ import {
   skillToDOM,
   behaviourToDOM,
   disciplineToDOM,
-  gradeToDOM,
+  levelToDOM,
   trackToDOM,
 } from "./formatters/index.js";
 import { sortTracksByName } from "./formatters/track/shared.js";
@@ -135,7 +135,7 @@ function renderIndex(data) {
             `${getConceptEmoji(framework, "job")} ${framework.entityDefinitions.job.title}`,
           ),
           " - ",
-          `${data.disciplines.length} disciplines, ${data.grades.length} grades, ${data.tracks.length} tracks`,
+          `${data.disciplines.length} disciplines, ${data.levels.length} levels, ${data.tracks.length} tracks`,
         ),
         li(
           {},
@@ -284,7 +284,7 @@ function sortDisciplinesByType(disciplines) {
 }
 
 /**
- * Render all job component slides (disciplines, grades, tracks)
+ * Render all job component slides (disciplines, levels, tracks)
  * @param {Object} data
  */
 function renderJobHandout(data) {
@@ -303,8 +303,8 @@ function renderJobHandout(data) {
     });
   });
 
-  const gradeSlides = data.grades.map((grade) => {
-    return gradeToDOM(grade, {
+  const levelSlides = data.levels.map((level) => {
+    return levelToDOM(level, {
       framework: data.framework,
       showBackLink: false,
     });
@@ -329,15 +329,15 @@ function renderJobHandout(data) {
     }),
     ...disciplineSlides,
 
-    // Grades chapter (moved before Tracks)
+    // Levels chapter (moved before Tracks)
     createChapterCover({
-      emojiIcon: getConceptEmoji(framework, "grade"),
-      title: framework.entityDefinitions.grade.title,
-      description: framework.entityDefinitions.grade.description,
+      emojiIcon: getConceptEmoji(framework, "level"),
+      title: framework.entityDefinitions.level.title,
+      description: framework.entityDefinitions.level.description,
     }),
-    ...gradeSlides,
+    ...levelSlides,
 
-    // Tracks chapter (moved after Grades)
+    // Tracks chapter (moved after Levels)
     createChapterCover({
       emojiIcon: getConceptEmoji(framework, "track"),
       title: framework.entityDefinitions.track.title,

package/src/index.html

@@ -83,7 +83,7 @@
           <div class="drawer-section">
             <span class="drawer-section-label">Browse</span>
             <a href="#/discipline">Disciplines</a>
-            <a href="#/grade">Grades</a>
+            <a href="#/level">Levels</a>
             <a href="#/track">Tracks</a>
             <a href="#/behaviour">Behaviours</a>
             <a href="#/skill">Skills</a>

package/src/lib/card-mappers.js

@@ -109,31 +109,31 @@ export function driverToCardConfig(driver) {
 }
 
 /**
- * Map grade to card config (for timeline)
- * @param {Object} grade
+ * Map level to card config (for timeline)
+ * @param {Object} level
  * @returns {Object}
  */
-export function gradeToCardConfig(grade) {
+export function levelToCardConfig(level) {
   return {
-    title: grade.displayName,
-    description: grade.scope || grade.truncatedDescription,
-    href: `/grade/${grade.id}`,
-    badges: [createBadge(grade.id, "default")],
+    title: level.displayName,
+    description: level.scope || level.truncatedDescription,
+    href: `/level/${level.id}`,
+    badges: [createBadge(level.id, "default")],
     meta: [
       createBadge(
-        `Primary: ${formatLevel(grade.baseSkillLevels?.primary)}`,
+        `Primary: ${formatLevel(level.baseSkillProficiencies?.primary)}`,
         "primary",
       ),
       createBadge(
-        `Secondary: ${formatLevel(grade.baseSkillLevels?.secondary)}`,
+        `Secondary: ${formatLevel(level.baseSkillProficiencies?.secondary)}`,
         "secondary",
       ),
       createBadge(
-        `Broad: ${formatLevel(grade.baseSkillLevels?.broad)}`,
+        `Broad: ${formatLevel(level.baseSkillProficiencies?.broad)}`,
         "broad",
       ),
     ],
-    yearsExperience: grade.yearsExperience,
+    yearsExperience: level.yearsExperience,
   };
 }
 
@@ -158,15 +158,15 @@ export function trackToCardConfig(track) {
  */
 export function jobToCardConfig(job) {
   const href = job.track
-    ? `/job/${job.discipline.id}/${job.grade.id}/${job.track.id}`
-    : `/job/${job.discipline.id}/${job.grade.id}`;
+    ? `/job/${job.discipline.id}/${job.level.id}/${job.track.id}`
+    : `/job/${job.discipline.id}/${job.level.id}`;
   return {
     title: job.title,
     description: job.track
-      ? `${job.discipline.specialization || job.discipline.name} at ${job.grade.professionalTitle} level on ${job.track.name} track`
-      : `${job.discipline.specialization || job.discipline.name} at ${job.grade.professionalTitle} level`,
+      ? `${job.discipline.specialization || job.discipline.name} at ${job.level.professionalTitle} level on ${job.track.name} track`
+      : `${job.discipline.specialization || job.discipline.name} at ${job.level.professionalTitle} level`,
     href,
-    badges: [createBadge(job.grade.id, "default")],
+    badges: [createBadge(job.level.id, "default")],
     meta: job.track ? [createBadge(job.track.name, "secondary")] : [],
   };
 }

package/src/lib/cli-command.js

@@ -21,7 +21,7 @@ const ROUTE_COMMANDS = [
     toCommand: () => "npx fit-pathway discipline",
   },
   { pattern: /^\/track$/, toCommand: () => "npx fit-pathway track" },
-  { pattern: /^\/grade$/, toCommand: () => "npx fit-pathway grade" },
+  { pattern: /^\/level$/, toCommand: () => "npx fit-pathway level" },
   { pattern: /^\/driver$/, toCommand: () => "npx fit-pathway driver" },
   { pattern: /^\/stage$/, toCommand: () => "npx fit-pathway stage" },
   { pattern: /^\/tool$/, toCommand: () => "npx fit-pathway tool" },
@@ -44,8 +44,8 @@ const ROUTE_COMMANDS = [
     toCommand: (m) => `npx fit-pathway track ${m[1]}`,
   },
   {
-    pattern: /^\/grade\/(.+)$/,
-    toCommand: (m) => `npx fit-pathway grade ${m[1]}`,
+    pattern: /^\/level\/(.+)$/,
+    toCommand: (m) => `npx fit-pathway level ${m[1]}`,
   },
   {
     pattern: /^\/driver\/(.+)$/,

package/src/lib/cli-output.js

@@ -126,11 +126,11 @@ export function formatTable(headers, rows, options = {}) {
 }
 
 /**
- * Format skill level with color
+ * Format skill proficiency with color
  * @param {string} level
  * @returns {string}
  */
-export function formatSkillLevel(level) {
+export function formatSkillProficiency(level) {
   const levelColors = {
     awareness: colors.gray,
     foundational: colors.blue,