@forwardimpact/pathway 0.1.0 → 0.3.0

package/app/formatters/job/description.js

@@ -3,41 +3,30 @@
  *
  * Formats job data into markdown job description content.
  * Parallels formatters/agent/profile.js in structure.
+ *
+ * Uses Mustache templates for flexible output formatting.
+ * Templates are loaded from data/ directory with fallback to templates/ directory.
  */
 
+import Mustache from "mustache";
+
 import {
   SKILL_LEVEL_ORDER,
   BEHAVIOUR_MATURITY_ORDER,
 } from "../../model/levels.js";
 
 /**
- * Format job as a markdown job description
+ * Prepare job data for template rendering
  * @param {Object} params
  * @param {Object} params.job - The job definition
  * @param {Object} params.discipline - The discipline
  * @param {Object} params.grade - The grade
- * @param {Object} params.track - The track
- * @returns {string} Markdown formatted job description
+ * @param {Object} [params.track] - The track (optional)
+ * @returns {Object} Data object ready for Mustache template
  */
-export function formatJobDescription({ job, discipline, grade, track }) {
-  const lines = [];
-
-  // Title
-  lines.push(`# ${job.title}`);
-  lines.push("");
-
-  // Meta information
-  lines.push(`- **Level:** ${grade.id}`);
-  lines.push(`- **Experience:** ${grade.typicalExperienceRange}`);
-  lines.push(`- **Track:** ${track.name}`);
-  lines.push("");
-
-  // Role Summary
-  lines.push("## ROLE SUMMARY");
-  lines.push("");
-
+function prepareJobDescriptionData({ job, discipline, grade, track }) {
   // Build role summary from discipline - use manager version if applicable
-  const isManagement = track.isManagement === true;
+  const isManagement = discipline.isManagement === true;
   let roleSummary =
     isManagement && discipline.managementRoleSummary
       ? discipline.managementRoleSummary
@@ -46,16 +35,9 @@ export function formatJobDescription({ job, discipline, grade, track }) {
   const { roleTitle, specialization } = discipline;
   roleSummary = roleSummary.replace(/\{roleTitle\}/g, roleTitle);
   roleSummary = roleSummary.replace(/\{specialization\}/g, specialization);
-  lines.push(roleSummary);
-  lines.push("");
-
-  // Add track context
-  if (track.roleContext) {
-    lines.push(track.roleContext);
-    lines.push("");
-  }
 
-  // Add grade expectations as natural paragraphs
+  // Build expectations paragraph
+  let expectationsParagraph = "";
   if (job.expectations) {
     const exp = job.expectations;
     const expectationSentences = [];
@@ -87,45 +69,20 @@ export function formatJobDescription({ job, discipline, grade, track }) {
     }
 
     if (expectationSentences.length > 0) {
-      lines.push(expectationSentences.join(" "));
-      lines.push("");
+      expectationsParagraph = expectationSentences.join(" ");
     }
   }
 
-  // Key Responsibilities
-  lines.push("## ROLE RESPONSIBILITIES");
-  lines.push("");
-
-  // Use derived responsibilities (already sorted by level descending)
-  const derivedResponsibilities = job.derivedResponsibilities || [];
-
-  for (const r of derivedResponsibilities) {
-    lines.push(`- **${r.capabilityName}:** ${r.responsibility}`);
-  }
-  lines.push("");
-
-  // Key Behaviours
-  lines.push("## ROLE BEHAVIOURS");
-  lines.push("");
-
   // Sort behaviours by maturity level (highest first)
   const sortedBehaviours = [...job.behaviourProfile].sort((a, b) => {
     const indexA = BEHAVIOUR_MATURITY_ORDER.indexOf(a.maturity);
     const indexB = BEHAVIOUR_MATURITY_ORDER.indexOf(b.maturity);
-    // Sort in reverse order (exemplifying first, emerging last)
     if (indexA === -1 && indexB === -1) return 0;
     if (indexA === -1) return 1;
     if (indexB === -1) return -1;
     return indexB - indexA;
   });
 
-  for (const behaviour of sortedBehaviours) {
-    lines.push(
-      `- **${behaviour.behaviourName}:** ${behaviour.maturityDescription || ""}`,
-    );
-  }
-  lines.push("");
-
   // Group skills by level
   const skillsByLevel = {};
   for (const skill of job.skillMatrix) {
@@ -136,41 +93,73 @@ export function formatJobDescription({ job, discipline, grade, track }) {
     skillsByLevel[level].push(skill);
   }
 
-  // Sort levels in a logical order using SKILL_LEVEL_ORDER from types.js
+  // Sort levels in reverse order (expert first, awareness last)
   const sortedLevels = Object.keys(skillsByLevel).sort((a, b) => {
     const indexA = SKILL_LEVEL_ORDER.indexOf(a.toLowerCase());
     const indexB = SKILL_LEVEL_ORDER.indexOf(b.toLowerCase());
-    // Sort in reverse order (expert first, awareness last)
     if (indexA === -1 && indexB === -1) return a.localeCompare(b);
     if (indexA === -1) return 1;
     if (indexB === -1) return -1;
     return indexB - indexA;
   });
 
-  for (const level of sortedLevels) {
-    const skills = skillsByLevel[level];
-    if (skills.length > 0) {
-      lines.push(`## ${level.toUpperCase()}-LEVEL SKILLS`);
-      lines.push("");
-      // Sort skills alphabetically by name
-      const sortedSkills = [...skills].sort((a, b) =>
-        (a.skillName || "").localeCompare(b.skillName || ""),
-      );
-      for (const skill of sortedSkills) {
-        lines.push(`- **${skill.skillName}:** ${skill.levelDescription || ""}`);
-      }
-      lines.push("");
-    }
-  }
+  // Keep only the top 2 skill levels for job descriptions
+  const topLevels = sortedLevels.slice(0, 2);
 
-  // Qualifications
-  lines.push("## QUALIFICATIONS");
-  lines.push("");
+  // Build skill levels array for template
+  const skillLevels = topLevels.map((level) => {
+    const skills = skillsByLevel[level];
+    const sortedSkills = [...skills].sort((a, b) =>
+      (a.skillName || "").localeCompare(b.skillName || ""),
+    );
+    return {
+      levelHeading: `${level.toUpperCase()}-LEVEL SKILLS`,
+      skills: sortedSkills.map((s) => ({
+        skillName: s.skillName,
+        levelDescription: s.levelDescription || "",
+      })),
+    };
+  });
 
-  if (grade.qualificationSummary) {
-    lines.push(grade.qualificationSummary);
-    lines.push("");
-  }
+  return {
+    title: job.title,
+    gradeId: grade.id,
+    typicalExperienceRange: grade.typicalExperienceRange,
+    trackName: track?.name || null,
+    roleSummary,
+    trackRoleContext: track?.roleContext || null,
+    expectationsParagraph: expectationsParagraph || null,
+    responsibilities: (job.derivedResponsibilities || []).map((r) => ({
+      capabilityName: r.capabilityName,
+      responsibility: r.responsibility,
+    })),
+    behaviours: sortedBehaviours.map((b) => ({
+      behaviourName: b.behaviourName,
+      maturityDescription: b.maturityDescription || "",
+    })),
+    skillLevels,
+    qualificationSummary:
+      (grade.qualificationSummary || "").replace(
+        /\{typicalExperienceRange\}/g,
+        grade.typicalExperienceRange || "",
+      ) || null,
+  };
+}
 
-  return lines.join("\n");
+/**
+ * Format job as a markdown job description using Mustache template
+ * @param {Object} params
+ * @param {Object} params.job - The job definition
+ * @param {Object} params.discipline - The discipline
+ * @param {Object} params.grade - The grade
+ * @param {Object} [params.track] - The track (optional)
+ * @param {string} template - Mustache template string
+ * @returns {string} Markdown formatted job description
+ */
+export function formatJobDescription(
+  { job, discipline, grade, track },
+  template,
+) {
+  const data = prepareJobDescriptionData({ job, discipline, grade, track });
+  return Mustache.render(template, data);
 }

package/app/formatters/job/dom.js

@@ -2,18 +2,7 @@
  * Job formatting for DOM/web output
  */
 
-import {
-  div,
-  h1,
-  h2,
-  p,
-  a,
-  span,
-  button,
-  section,
-  details,
-  summary,
-} from "../../lib/render.js";
+import { div, h1, h2, p, a, span, button, section } from "../../lib/render.js";
 import { createBackLink } from "../../components/nav.js";
 import {
   createDetailSection,
@@ -39,6 +28,7 @@ import { formatJobDescription } from "./description.js";
  * @param {Object} [options.discipline] - Discipline entity for job description
  * @param {Object} [options.grade] - Grade entity for job description
  * @param {Object} [options.track] - Track entity for job description
+ * @param {string} [options.jobTemplate] - Mustache template for job description
  * @returns {HTMLElement}
  */
 export function jobToDOM(view, options = {}) {
@@ -50,9 +40,10 @@ export function jobToDOM(view, options = {}) {
     discipline,
     grade,
     track,
+    jobTemplate,
   } = options;
 
-  const hasEntities = discipline && grade && track;
+  const hasEntities = discipline && grade && jobTemplate;
 
   return div(
     { className: "job-detail-page" },
@@ -108,6 +99,7 @@ export function jobToDOM(view, options = {}) {
           discipline,
           grade,
           track,
+          template: jobTemplate,
         })
       : null,
 
@@ -140,14 +132,6 @@ export function jobToDOM(view, options = {}) {
                 ),
               })
             : null,
-
-          // Handoff Checklists
-          view.checklists && hasChecklistItems(view.checklists)
-            ? createDetailSection({
-                title: "📋 Handoff Checklists",
-                content: createChecklistSections(view.checklists),
-              })
-            : null,
         )
       : null,
 
@@ -164,6 +148,7 @@ export function jobToDOM(view, options = {}) {
           discipline,
           grade,
           track,
+          template: jobTemplate,
         })
       : null,
   );
@@ -211,84 +196,6 @@ function getScoreColor(score) {
   return "#ef4444"; // Red
 }
 
-/**
- * Check if any checklist has items
- * @param {Object} checklists - Checklists object keyed by handoff type
- * @returns {boolean}
- */
-function hasChecklistItems(checklists) {
-  for (const items of Object.values(checklists)) {
-    if (items && items.length > 0) {
-      return true;
-    }
-  }
-  return false;
-}
-
-/**
- * Create collapsible checklist sections for all handoffs
- * @param {Object} checklists - Checklists object keyed by handoff type
- * @returns {HTMLElement}
- */
-function createChecklistSections(checklists) {
-  const handoffLabels = {
-    plan_to_code: "📋 → 💻 Plan → Code",
-    code_to_review: "💻 → ✅ Code → Review",
-  };
-
-  const sections = Object.entries(checklists)
-    .filter(([_, items]) => items && items.length > 0)
-    .map(([handoff, groups]) => {
-      const label = handoffLabels[handoff] || handoff;
-      const totalItems = groups.reduce((sum, g) => sum + g.items.length, 0);
-
-      return details(
-        { className: "checklist-section" },
-        summary(
-          { className: "checklist-section-header" },
-          span({ className: "checklist-section-label" }, label),
-          span({ className: "badge badge-default" }, `${totalItems} items`),
-        ),
-        div(
-          { className: "checklist-section-content" },
-          ...groups.map((group) => createChecklistGroup(group)),
-        ),
-      );
-    });
-
-  return div({ className: "checklist-sections" }, ...sections);
-}
-
-/**
- * Create a checklist group for a capability
- * @param {Object} group - Group with capability, level, and items
- * @returns {HTMLElement}
- */
-function createChecklistGroup(group) {
-  const emoji = group.capability.emoji || "📌";
-  const capabilityName = group.capability.name || group.capability.id;
-
-  return div(
-    { className: "checklist-group" },
-    div(
-      { className: "checklist-group-header" },
-      span({ className: "checklist-emoji" }, emoji),
-      span({ className: "checklist-capability" }, capabilityName),
-      span({ className: "badge badge-secondary" }, group.level),
-    ),
-    div(
-      { className: "checklist-items" },
-      ...group.items.map((item) =>
-        div(
-          { className: "checklist-item" },
-          span({ className: "checklist-checkbox" }, "☐"),
-          span({}, item),
-        ),
-      ),
-    ),
-  );
-}
-
 /**
  * Create the job description section with copy button
  * @param {Object} params
@@ -296,15 +203,25 @@ function createChecklistGroup(group) {
  * @param {Object} params.discipline - The discipline
  * @param {Object} params.grade - The grade
  * @param {Object} params.track - The track
+ * @param {string} params.template - Mustache template for job description
  * @returns {HTMLElement} The job description section element
  */
-export function createJobDescriptionSection({ job, discipline, grade, track }) {
-  const markdown = formatJobDescription({
-    job,
-    discipline,
-    grade,
-    track,
-  });
+export function createJobDescriptionSection({
+  job,
+  discipline,
+  grade,
+  track,
+  template,
+}) {
+  const markdown = formatJobDescription(
+    {
+      job,
+      discipline,
+      grade,
+      track,
+    },
+    template,
+  );
 
   const copyButton = button(
     {
@@ -388,15 +305,25 @@ export function createJobDescriptionSection({ job, discipline, grade, track }) {
  * @param {Object} params.discipline - The discipline
  * @param {Object} params.grade - The grade
  * @param {Object} params.track - The track
+ * @param {string} params.template - Mustache template for job description
  * @returns {HTMLElement} The job description HTML element (print-only)
  */
-export function createJobDescriptionHtml({ job, discipline, grade, track }) {
-  const markdown = formatJobDescription({
-    job,
-    discipline,
-    grade,
-    track,
-  });
+export function createJobDescriptionHtml({
+  job,
+  discipline,
+  grade,
+  track,
+  template,
+}) {
+  const markdown = formatJobDescription(
+    {
+      job,
+      discipline,
+      grade,
+      track,
+    },
+    template,
+  );
 
   const html = markdownToHtml(markdown);
 

package/app/formatters/job/markdown.js

@@ -15,9 +15,10 @@ import { SKILL_LEVEL_ORDER } from "../../model/levels.js";
  * Format job detail as markdown
  * @param {Object} view - Job detail view from presenter
  * @param {Object} [entities] - Original entities (for job description)
+ * @param {string} [jobTemplate] - Mustache template for job description
  * @returns {string}
  */
-export function jobToMarkdown(view, entities = {}) {
+export function jobToMarkdown(view, entities = {}, jobTemplate) {
   const lines = [
     `# ${view.title}`,
     "",
@@ -77,23 +78,26 @@ export function jobToMarkdown(view, entities = {}) {
   }
 
   // Job Description (copyable markdown)
-  if (entities.discipline && entities.grade && entities.track) {
+  if (entities.discipline && entities.grade && jobTemplate) {
     lines.push("---", "");
     lines.push("## Job Description", "");
     lines.push("```markdown");
     lines.push(
-      formatJobDescription({
-        job: {
-          title: view.title,
-          skillMatrix: view.skillMatrix,
-          behaviourProfile: view.behaviourProfile,
-          expectations: view.expectations,
-          derivedResponsibilities: view.derivedResponsibilities,
+      formatJobDescription(
+        {
+          job: {
+            title: view.title,
+            skillMatrix: view.skillMatrix,
+            behaviourProfile: view.behaviourProfile,
+            expectations: view.expectations,
+            derivedResponsibilities: view.derivedResponsibilities,
+          },
+          discipline: entities.discipline,
+          grade: entities.grade,
+          track: entities.track,
         },
-        discipline: entities.discipline,
-        grade: entities.grade,
-        track: entities.track,
-      }),
+        jobTemplate,
+      ),
     );
     lines.push("```");
   }