@forwardimpact/pathway 0.20.0 → 0.22.0

package/src/formatters/{grade → level}/markdown.js

@@ -1,27 +1,27 @@
 /**
- * Grade formatting for markdown/CLI output
+ * Level formatting for markdown/CLI output
  */
 
 import { tableToMarkdown, capitalize } from "../shared.js";
-import { prepareGradesList, prepareGradeDetail } from "./shared.js";
-import { getConceptEmoji } from "@forwardimpact/schema/levels";
+import { prepareLevelsList, prepareLevelDetail } from "./shared.js";
+import { getConceptEmoji } from "@forwardimpact/map/levels";
 
 /**
- * Format grade list as markdown
- * @param {Array} grades - Raw grade entities
+ * Format level list as markdown
+ * @param {Array} levels - Raw level entities
  * @param {Object} [framework] - Framework config for emojis
  * @returns {string}
  */
-export function gradeListToMarkdown(grades, framework) {
-  const { items } = prepareGradesList(grades);
-  const emoji = framework ? getConceptEmoji(framework, "grade") : "📊";
-  const lines = [`# ${emoji} Grades`, ""];
+export function levelListToMarkdown(levels, framework) {
+  const { items } = prepareLevelsList(levels);
+  const emoji = framework ? getConceptEmoji(framework, "level") : "📊";
+  const lines = [`# ${emoji} Levels`, ""];
 
   const rows = items.map((g) => [
     g.id,
     g.displayName,
     g.typicalExperienceRange || "-",
-    capitalize(g.baseSkillLevels?.primary || "-"),
+    capitalize(g.baseSkillProficiencies?.primary || "-"),
   ]);
 
   lines.push(tableToMarkdown(["ID", "Name", "Years", "Primary Level"], rows));
@@ -31,14 +31,14 @@ export function gradeListToMarkdown(grades, framework) {
 }
 
 /**
- * Format grade detail as markdown
- * @param {Object} grade - Raw grade entity
+ * Format level detail as markdown
+ * @param {Object} level - Raw level entity
  * @param {Object} [framework] - Framework config for emojis
  * @returns {string}
  */
-export function gradeToMarkdown(grade, framework) {
-  const view = prepareGradeDetail(grade);
-  const emoji = framework ? getConceptEmoji(framework, "grade") : "📊";
+export function levelToMarkdown(level, framework) {
+  const view = prepareLevelDetail(level);
+  const emoji = framework ? getConceptEmoji(framework, "level") : "📊";
   const lines = [`# ${emoji} ${view.displayName} (${view.id})`, ""];
 
   if (view.typicalExperienceRange) {
@@ -57,27 +57,18 @@ export function gradeToMarkdown(grade, framework) {
     lines.push("");
   }
 
-  // Base skill levels
-  lines.push("## Base Skill Levels", "");
-  const skillRows = Object.entries(view.baseSkillLevels).map(
+  // Base skill proficiencies
+  lines.push("## Base Skill Proficiencies", "");
+  const skillRows = Object.entries(view.baseSkillProficiencies).map(
     ([type, level]) => [capitalize(type), capitalize(level)],
   );
   lines.push(tableToMarkdown(["Skill Type", "Level"], skillRows));
   lines.push("");
 
   // Base behaviour maturity
-  if (
-    view.baseBehaviourMaturity &&
-    Object.keys(view.baseBehaviourMaturity).length > 0
-  ) {
+  if (view.baseBehaviourMaturity) {
     lines.push("## Base Behaviour Maturity", "");
-    const behaviourRows = Object.entries(view.baseBehaviourMaturity).map(
-      ([type, maturity]) => [
-        capitalize(type),
-        capitalize(maturity.replace(/_/g, " ")),
-      ],
-    );
-    lines.push(tableToMarkdown(["Type", "Maturity"], behaviourRows));
+    lines.push(capitalize(view.baseBehaviourMaturity.replace(/_/g, " ")));
     lines.push("");
   }
 

package/src/formatters/{grade → level}/microdata.js

@@ -1,7 +1,7 @@
 /**
- * Grade formatting for microdata HTML output
+ * Level formatting for microdata HTML output
  *
- * Generates clean, class-less HTML with microdata aligned with grades.schema.json
+ * Generates clean, class-less HTML with microdata aligned with levels.schema.json
  * RDF vocab: https://www.forwardimpact.team/schema/rdf/
  */
 
@@ -16,19 +16,19 @@ import {
   formatLevelName,
   htmlDocument,
 } from "../microdata-shared.js";
-import { prepareGradesList, prepareGradeDetail } from "./shared.js";
+import { prepareLevelsList, prepareLevelDetail } from "./shared.js";
 
 /**
- * Format grade list as microdata HTML
- * @param {Array} grades - Raw grade entities
+ * Format level list as microdata HTML
+ * @param {Array} levels - Raw level entities
  * @returns {string} HTML with microdata
  */
-export function gradeListToMicrodata(grades) {
-  const { items } = prepareGradesList(grades);
+export function levelListToMicrodata(levels) {
+  const { items } = prepareLevelsList(levels);
 
   const content = items
     .map(
-      (g) => `${openTag("article", { itemtype: "Grade", itemid: `#${g.id}` })}
+      (g) => `${openTag("article", { itemtype: "Level", itemid: `#${g.id}` })}
 ${prop("h2", "id", g.id)}
 <p>${escapeHtml(g.displayName)}</p>
 ${g.typicalExperienceRange ? prop("p", "typicalExperienceRange", g.typicalExperienceRange) : ""}
@@ -38,21 +38,21 @@ ${metaTag("ordinalRank", String(g.ordinalRank))}
     .join("\n");
 
   return htmlDocument(
-    "Grades",
+    "Levels",
     `<main>
-<h1>Grades</h1>
+<h1>Levels</h1>
 ${content}
 </main>`,
   );
 }
 
 /**
- * Format grade detail as microdata HTML
- * @param {Object} grade - Raw grade entity
+ * Format level detail as microdata HTML
+ * @param {Object} level - Raw level entity
  * @returns {string} HTML with microdata
  */
-export function gradeToMicrodata(grade) {
-  const view = prepareGradeDetail(grade);
+export function levelToMicrodata(level) {
+  const view = prepareLevelDetail(level);
 
   if (!view) return "";
 
@@ -78,9 +78,12 @@ export function gradeToMicrodata(grade) {
     sections.push(section("Titles", dl(titlePairs), 2));
   }
 
-  // Base skill levels - using BaseSkillLevels itemtype
-  if (view.baseSkillLevels && Object.keys(view.baseSkillLevels).length > 0) {
-    const levelPairs = Object.entries(view.baseSkillLevels).map(
+  // Base skill proficiencies - using BaseSkillProficiencies itemtype
+  if (
+    view.baseSkillProficiencies &&
+    Object.keys(view.baseSkillProficiencies).length > 0
+  ) {
+    const levelPairs = Object.entries(view.baseSkillProficiencies).map(
       ([type, level]) => ({
         term: formatLevelName(type),
         definition: formatLevelName(level),
@@ -89,8 +92,8 @@ export function gradeToMicrodata(grade) {
     );
     sections.push(
       section(
-        "Base Skill Levels",
-        `${openTag("div", { itemtype: "BaseSkillLevels", itemprop: "baseSkillLevels" })}
+        "Base Skill Proficiencies",
+        `${openTag("div", { itemtype: "BaseSkillProficiencies", itemprop: "baseSkillProficiencies" })}
 ${dl(levelPairs)}
 </div>`,
         2,
@@ -99,26 +102,13 @@ ${dl(levelPairs)}
   }
 
   // Base behaviour maturity - link to BehaviourMaturity
-  if (
-    view.baseBehaviourMaturity &&
-    Object.keys(view.baseBehaviourMaturity).length > 0
-  ) {
-    const maturityPairs = Object.entries(view.baseBehaviourMaturity).map(
-      ([type, maturity]) => ({
-        term: formatLevelName(type),
-        definition: formatLevelName(maturity),
-      }),
-    );
-    // Handle both single value and object cases
-    const maturityContent =
-      typeof grade.baseBehaviourMaturity === "string"
-        ? `${linkTag("baseBehaviourMaturity", `#${grade.baseBehaviourMaturity}`)}
-<p>${formatLevelName(grade.baseBehaviourMaturity)}</p>`
-        : dl(maturityPairs);
+  if (view.baseBehaviourMaturity) {
+    const maturityContent = `${linkTag("baseBehaviourMaturity", `#${level.baseBehaviourMaturity}`)}
+<p>${formatLevelName(level.baseBehaviourMaturity)}</p>`;
     sections.push(section("Base Behaviour Maturity", maturityContent, 2));
   }
 
-  // Expectations - using GradeExpectations itemtype
+  // Expectations - using LevelExpectations itemtype
   if (view.expectations && Object.keys(view.expectations).length > 0) {
     const expectationPairs = Object.entries(view.expectations).map(
       ([key, value]) => ({
@@ -130,7 +120,7 @@ ${dl(levelPairs)}
     sections.push(
       section(
         "Expectations",
-        `${openTag("div", { itemtype: "GradeExpectations", itemprop: "expectations" })}
+        `${openTag("div", { itemtype: "LevelExpectations", itemprop: "expectations" })}
 ${dl(expectationPairs)}
 </div>`,
         2,
@@ -139,7 +129,7 @@ ${dl(expectationPairs)}
   }
 
   const body = `<main>
-${openTag("article", { itemtype: "Grade", itemid: `#${view.id}` })}
+${openTag("article", { itemtype: "Level", itemid: `#${view.id}` })}
 <h1>${prop("span", "id", view.id)} — ${escapeHtml(view.displayName)}</h1>
 ${metaTag("ordinalRank", String(view.ordinalRank))}
 ${view.typicalExperienceRange ? prop("p", "typicalExperienceRange", `Experience: ${view.typicalExperienceRange}`) : ""}

package/src/formatters/level/shared.js

@@ -0,0 +1,86 @@
+/**
+ * Level presentation helpers
+ *
+ * Shared utilities for formatting level data across DOM and markdown outputs.
+ */
+
+/**
+ * Get level display name (shows both professional and management titles)
+ * @param {Object} level
+ * @returns {string}
+ */
+export function getLevelDisplayName(level) {
+  if (level.professionalTitle && level.managementTitle) {
+    if (level.professionalTitle === level.managementTitle) {
+      return level.professionalTitle;
+    }
+    return `${level.professionalTitle} / ${level.managementTitle}`;
+  }
+  return level.professionalTitle || level.managementTitle || level.id;
+}
+
+/**
+ * @typedef {Object} LevelListItem
+ * @property {string} id
+ * @property {string} displayName
+ * @property {number} ordinalRank
+ * @property {string|null} typicalExperienceRange
+ * @property {Object} baseSkillProficiencies
+ * @property {string|null} impactScope
+ */
+
+/**
+ * Transform levels for list view
+ * @param {Array} levels - Raw level entities
+ * @returns {{ items: LevelListItem[] }}
+ */
+export function prepareLevelsList(levels) {
+  const sortedLevels = [...levels].sort(
+    (a, b) => a.ordinalRank - b.ordinalRank,
+  );
+
+  const items = sortedLevels.map((level) => ({
+    id: level.id,
+    displayName: getLevelDisplayName(level),
+    ordinalRank: level.ordinalRank,
+    typicalExperienceRange: level.typicalExperienceRange || null,
+    baseSkillProficiencies: level.baseSkillProficiencies || {},
+    impactScope: level.expectations?.impactScope || null,
+  }));
+
+  return { items };
+}
+
+/**
+ * @typedef {Object} LevelDetailView
+ * @property {string} id
+ * @property {string} displayName
+ * @property {string} professionalTitle
+ * @property {string} managementTitle
+ * @property {number} ordinalRank
+ * @property {string|null} typicalExperienceRange
+ * @property {Object} baseSkillProficiencies
+ * @property {Object} baseBehaviourMaturity
+ * @property {Object} expectations
+ */
+
+/**
+ * Transform level for detail view
+ * @param {Object} level - Raw level entity
+ * @returns {LevelDetailView|null}
+ */
+export function prepareLevelDetail(level) {
+  if (!level) return null;
+
+  return {
+    id: level.id,
+    displayName: getLevelDisplayName(level),
+    professionalTitle: level.professionalTitle || null,
+    managementTitle: level.managementTitle || null,
+    ordinalRank: level.ordinalRank,
+    typicalExperienceRange: level.typicalExperienceRange || null,
+    baseSkillProficiencies: level.baseSkillProficiencies || {},
+    baseBehaviourMaturity: level.baseBehaviourMaturity || {},
+    expectations: level.expectations || {},
+  };
+}

package/src/formatters/progress/markdown.js

@@ -29,7 +29,7 @@ export function progressToMarkdown(view) {
 
   // Skill changes
   const skillsWithChanges = view.skillChanges.filter(
-    (s) => s.levelChange !== 0,
+    (s) => s.proficiencyChange !== 0,
   );
   if (skillsWithChanges.length > 0) {
     lines.push("## Skill Changes", "");
@@ -39,7 +39,7 @@ export function progressToMarkdown(view) {
       formatLevel(s.fromLevel || "-"),
       "→",
       formatLevel(s.toLevel),
-      formatChange(s.levelChange),
+      formatChange(s.proficiencyChange),
     ]);
     lines.push(
       tableToMarkdown(["Skill", "Type", "From", "", "To", "Change"], skillRows),

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;