@forwardimpact/pathway 0.1.0

package/app/formatters/questions/markdown.js

@@ -0,0 +1,303 @@
+/**
+ * Questions Markdown Formatter
+ *
+ * Formats questions for terminal output as tables and lists.
+ */
+
+import { SKILL_LEVELS, BEHAVIOUR_MATURITIES } from "./shared.js";
+
+/**
+ * Level abbreviations for compact display
+ */
+const LEVEL_ABBREVS = {
+  awareness: "aware",
+  foundational: "found",
+  working: "work",
+  practitioner: "pract",
+  expert: "expert",
+};
+
+/**
+ * Maturity abbreviations for compact display
+ */
+const MATURITY_ABBREVS = {
+  emerging: "emerg",
+  developing: "dev",
+  practicing: "pract",
+  role_modeling: "role",
+  exemplifying: "exemp",
+};
+
+/**
+ * Truncate text to max length with ellipsis
+ * @param {string} text
+ * @param {number} maxLen
+ * @returns {string}
+ */
+function truncate(text, maxLen) {
+  if (text.length <= maxLen) return text;
+  return text.slice(0, maxLen - 1) + "…";
+}
+
+/**
+ * Pad string to width
+ * @param {string} str
+ * @param {number} width
+ * @returns {string}
+ */
+function pad(str, width) {
+  return str.padEnd(width);
+}
+
+/**
+ * Format stats-only output
+ * @param {Object} view - Questions view
+ * @param {Array} skills - Skills data
+ * @returns {string}
+ */
+function formatStats(view, skills) {
+  const lines = [];
+  const { stats } = view;
+
+  // Skill question counts
+  lines.push("SKILL QUESTION COUNTS");
+  lines.push("═".repeat(75));
+  lines.push("");
+
+  // Header
+  const skillHeader =
+    pad("Skill", 30) +
+    SKILL_LEVELS.map((l) => pad(LEVEL_ABBREVS[l], 7)).join("") +
+    "TOTAL";
+  lines.push(skillHeader);
+  lines.push("─".repeat(75));
+
+  // Rows
+  const sortedSkillIds = Object.keys(stats.skillStats).sort();
+  let skillTotal = 0;
+  const levelTotals = {};
+
+  for (const skillId of sortedSkillIds) {
+    const skillData = stats.skillStats[skillId];
+    const skill = skills.find((s) => s.id === skillId);
+    const name = skill ? truncate(skill.name, 28) : skillId;
+
+    const row =
+      pad(name, 30) +
+      SKILL_LEVELS.map((l) => {
+        const count = skillData[l] || 0;
+        levelTotals[l] = (levelTotals[l] || 0) + count;
+        return pad(String(count), 7);
+      }).join("") +
+      String(skillData.total || 0);
+
+    lines.push(row);
+    skillTotal += skillData.total || 0;
+  }
+
+  lines.push("─".repeat(75));
+  const totalsRow =
+    pad("TOTAL", 30) +
+    SKILL_LEVELS.map((l) => pad(String(levelTotals[l] || 0), 7)).join("") +
+    String(skillTotal);
+  lines.push(totalsRow);
+  lines.push("");
+
+  // Behaviour question counts
+  lines.push("BEHAVIOUR QUESTION COUNTS");
+  lines.push("═".repeat(75));
+  lines.push("");
+
+  const behaviourHeader =
+    pad("Behaviour", 30) +
+    BEHAVIOUR_MATURITIES.map((m) => pad(MATURITY_ABBREVS[m], 7)).join("") +
+    "TOTAL";
+  lines.push(behaviourHeader);
+  lines.push("─".repeat(75));
+
+  const sortedBehaviourIds = Object.keys(stats.behaviourStats).sort();
+  let behaviourTotal = 0;
+  const maturityTotals = {};
+
+  for (const behaviourId of sortedBehaviourIds) {
+    const behaviourData = stats.behaviourStats[behaviourId];
+    const name = truncate(behaviourId.replace(/_/g, " "), 28);
+
+    const row =
+      pad(name, 30) +
+      BEHAVIOUR_MATURITIES.map((m) => {
+        const count = behaviourData[m] || 0;
+        maturityTotals[m] = (maturityTotals[m] || 0) + count;
+        return pad(String(count), 7);
+      }).join("") +
+      String(behaviourData.total || 0);
+
+    lines.push(row);
+    behaviourTotal += behaviourData.total || 0;
+  }
+
+  lines.push("─".repeat(75));
+  const bTotalsRow =
+    pad("TOTAL", 30) +
+    BEHAVIOUR_MATURITIES.map((m) =>
+      pad(String(maturityTotals[m] || 0), 7),
+    ).join("") +
+    String(behaviourTotal);
+  lines.push(bTotalsRow);
+  lines.push("");
+
+  // Identify gaps (skills with < 2 questions per level)
+  const gaps = [];
+  for (const skillId of sortedSkillIds) {
+    const skillData = stats.skillStats[skillId];
+    for (const level of SKILL_LEVELS) {
+      if ((skillData[level] || 0) < 1) {
+        gaps.push(`${skillId}: missing ${level} questions`);
+      }
+    }
+  }
+
+  if (gaps.length > 0) {
+    lines.push("⚠️  GAPS:");
+    for (const gap of gaps.slice(0, 10)) {
+      lines.push(`  - ${gap}`);
+    }
+    if (gaps.length > 10) {
+      lines.push(`  ... and ${gaps.length - 10} more`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Format table output for questions at a level/maturity
+ * @param {Object} view - Questions view
+ * @returns {string}
+ */
+function formatTable(view) {
+  const lines = [];
+  const { filter, questions, stats } = view;
+
+  // Header
+  const levelOrMaturity = filter.level || filter.maturity || "ALL";
+  const sourceType = filter.level
+    ? "skills"
+    : filter.maturity
+      ? "behaviours"
+      : "sources";
+  lines.push(
+    `${levelOrMaturity.toUpperCase()} LEVEL QUESTIONS (${stats.totalQuestions} from ${Object.keys(stats.bySource).length} ${sourceType})`,
+  );
+  lines.push("═".repeat(80));
+  lines.push("");
+
+  // Table header
+  lines.push(pad("Source", 28) + " │ " + pad("Question", 45) + " │ Min");
+  lines.push("─".repeat(28) + "─┼─" + "─".repeat(45) + "─┼─" + "───");
+
+  // Group by source
+  const bySource = {};
+  for (const q of questions) {
+    if (!bySource[q.source]) {
+      bySource[q.source] = { name: q.sourceName, questions: [] };
+    }
+    bySource[q.source].questions.push(q);
+  }
+
+  for (const data of Object.values(bySource).sort((a, b) =>
+    a.name.localeCompare(b.name),
+  )) {
+    for (const q of data.questions) {
+      const source = truncate(data.name, 26);
+      const text = truncate(q.text, 43);
+      const mins = String(q.expectedDurationMinutes);
+      lines.push(pad(source, 28) + " │ " + pad(text, 45) + " │ " + mins);
+    }
+  }
+
+  lines.push("");
+  return lines.join("\n");
+}
+
+/**
+ * Format single source deep dive
+ * @param {Object} view - Questions view
+ * @returns {string}
+ */
+function formatSingleSource(view) {
+  const lines = [];
+  const { questions, stats } = view;
+
+  if (questions.length === 0) {
+    return "No questions found.";
+  }
+
+  const sourceName = questions[0].sourceName;
+  const sourceType = questions[0].sourceType;
+
+  lines.push(`${sourceName} QUESTIONS (${stats.totalQuestions} total)`);
+  lines.push("═".repeat(60));
+  lines.push("");
+
+  // Group by level/maturity
+  const byLevel = {};
+  for (const q of questions) {
+    if (!byLevel[q.level]) {
+      byLevel[q.level] = [];
+    }
+    byLevel[q.level].push(q);
+  }
+
+  const orderedLevels =
+    sourceType === "skill" ? SKILL_LEVELS : BEHAVIOUR_MATURITIES;
+
+  for (const level of orderedLevels) {
+    if (!byLevel[level]) continue;
+
+    lines.push(level.toUpperCase());
+    for (const q of byLevel[level]) {
+      lines.push(`  • [${q.id}] ${q.text}`);
+      lines.push(`    Duration: ${q.expectedDurationMinutes} min`);
+      if (q.lookingFor.length > 0) {
+        lines.push("    Looking for:");
+        for (const item of q.lookingFor) {
+          lines.push(`      - ${item}`);
+        }
+      }
+      if (q.followUps.length > 0) {
+        lines.push("    Follow-ups:");
+        for (const fu of q.followUps) {
+          lines.push(`      → ${fu}`);
+        }
+      }
+      lines.push("");
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Format questions as markdown for terminal
+ * @param {Object} view - Questions view from prepareQuestionsView
+ * @param {Object} options - Format options
+ * @param {boolean} options.stats - Stats only
+ * @param {Array} options.skills - Skills data for name resolution
+ * @returns {string}
+ */
+export function questionsToMarkdown(view, options = {}) {
+  // Stats only mode
+  if (options.stats) {
+    return formatStats(view, options.skills || []);
+  }
+
+  // Single source deep dive
+  const uniqueSources = new Set(view.questions.map((q) => q.source));
+  if (uniqueSources.size === 1) {
+    return formatSingleSource(view);
+  }
+
+  // Table format (default)
+  return formatTable(view);
+}

package/app/formatters/questions/shared.js

@@ -0,0 +1,274 @@
+/**
+ * Questions presentation helpers
+ *
+ * Shared utilities for formatting question data across output formats.
+ */
+
+/**
+ * Skill levels in order
+ */
+export const SKILL_LEVELS = [
+  "awareness",
+  "foundational",
+  "working",
+  "practitioner",
+  "expert",
+];
+
+/**
+ * Behaviour maturities in order
+ */
+export const BEHAVIOUR_MATURITIES = [
+  "emerging",
+  "developing",
+  "practicing",
+  "role_modeling",
+  "exemplifying",
+];
+
+/**
+ * @typedef {Object} QuestionsFilter
+ * @property {string|null} level - Skill level filter
+ * @property {string|null} maturity - Behaviour maturity filter
+ * @property {string[]|null} skills - Skill IDs to include
+ * @property {string[]|null} behaviours - Behaviour IDs to include
+ * @property {string|null} capability - Capability filter for skills
+ */
+
+/**
+ * @typedef {Object} FlattenedQuestion
+ * @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} id - Question ID
+ * @property {string} text - Question text
+ * @property {string[]} lookingFor - Expected answer indicators
+ * @property {number} expectedDurationMinutes - Time estimate
+ * @property {string[]} [followUps] - Follow-up questions
+ */
+
+/**
+ * @typedef {Object} QuestionsView
+ * @property {QuestionsFilter} filter - Applied filters
+ * @property {FlattenedQuestion[]} questions - Flattened questions
+ * @property {Object} stats - Question statistics
+ */
+
+/**
+ * Parse filter options from CLI args
+ * @param {Object} options - CLI options
+ * @returns {QuestionsFilter}
+ */
+export function parseFilters(options) {
+  return {
+    level: options.level || null,
+    maturity: options.maturity || null,
+    skills: options.skill ? options.skill.split(",") : null,
+    behaviours: options.behaviour ? options.behaviour.split(",") : null,
+    capability: options.capability || null,
+  };
+}
+
+/**
+ * Get skill name by ID
+ * @param {string} skillId
+ * @param {Array} skills
+ * @returns {string}
+ */
+function getSkillName(skillId, skills) {
+  const skill = skills.find((s) => s.id === skillId);
+  return skill ? skill.name : skillId;
+}
+
+/**
+ * Get behaviour name by ID
+ * @param {string} behaviourId
+ * @param {Array} behaviours
+ * @returns {string}
+ */
+function getBehaviourName(behaviourId, behaviours) {
+  const behaviour = behaviours.find((b) => b.id === behaviourId);
+  return behaviour ? behaviour.name : behaviourId;
+}
+
+/**
+ * Get skill capability by ID
+ * @param {string} skillId
+ * @param {Array} skills
+ * @returns {string|null}
+ */
+function getSkillCapability(skillId, skills) {
+  const skill = skills.find((s) => s.id === skillId);
+  return skill ? skill.capability : null;
+}
+
+/**
+ * Flatten all questions from question bank
+ * @param {Object} questionBank
+ * @param {Array} skills
+ * @param {Array} behaviours
+ * @param {QuestionsFilter} filter
+ * @returns {FlattenedQuestion[]}
+ */
+export function flattenQuestions(questionBank, skills, behaviours, filter) {
+  const questions = [];
+
+  // Process skill questions
+  for (const [skillId, levels] of Object.entries(
+    questionBank.skillLevels || {},
+  )) {
+    const skillName = getSkillName(skillId, skills);
+    const capability = getSkillCapability(skillId, skills);
+
+    // Filter by skill IDs
+    if (filter.skills && !filter.skills.includes(skillId)) continue;
+
+    // Skip skills if filtering by specific behaviours
+    if (filter.behaviours) continue;
+
+    // Filter by capability
+    if (filter.capability && capability !== filter.capability) continue;
+
+    for (const [level, levelQuestions] of Object.entries(levels)) {
+      // Filter by level
+      if (filter.level && level !== filter.level) continue;
+
+      // Skip if filtering by maturity (behaviour-only filter)
+      if (filter.maturity) continue;
+
+      for (const q of levelQuestions) {
+        questions.push({
+          source: skillId,
+          sourceName: skillName,
+          sourceType: "skill",
+          level,
+          id: q.id,
+          text: q.text,
+          lookingFor: q.lookingFor || [],
+          expectedDurationMinutes: q.expectedDurationMinutes || 5,
+          followUps: q.followUps || [],
+        });
+      }
+    }
+  }
+
+  // Process behaviour questions
+  for (const [behaviourId, maturities] of Object.entries(
+    questionBank.behaviourMaturities || {},
+  )) {
+    const behaviourName = getBehaviourName(behaviourId, behaviours);
+
+    // Filter by behaviour IDs
+    if (filter.behaviours && !filter.behaviours.includes(behaviourId)) continue;
+
+    // Skip behaviours if filtering by capability (skill-only filter)
+    if (filter.capability) continue;
+
+    // Skip behaviours if filtering by specific skills
+    if (filter.skills) continue;
+
+    for (const [maturity, maturityQuestions] of Object.entries(maturities)) {
+      // Filter by maturity
+      if (filter.maturity && maturity !== filter.maturity) continue;
+
+      // Skip if filtering by level (skill-only filter)
+      if (filter.level) continue;
+
+      for (const q of maturityQuestions) {
+        questions.push({
+          source: behaviourId,
+          sourceName: behaviourName,
+          sourceType: "behaviour",
+          level: maturity,
+          id: q.id,
+          text: q.text,
+          lookingFor: q.lookingFor || [],
+          expectedDurationMinutes: q.expectedDurationMinutes || 5,
+          followUps: q.followUps || [],
+        });
+      }
+    }
+  }
+
+  return questions;
+}
+
+/**
+ * Calculate question statistics
+ * @param {FlattenedQuestion[]} questions
+ * @param {Object} questionBank
+ * @returns {Object}
+ */
+export function calculateStats(questions, questionBank) {
+  const bySource = {};
+  const byLevel = {};
+
+  for (const q of questions) {
+    bySource[q.source] = (bySource[q.source] || 0) + 1;
+    byLevel[q.level] = (byLevel[q.level] || 0) + 1;
+  }
+
+  // Calculate full stats for skills and behaviours
+  const skillStats = {};
+  for (const [skillId, levels] of Object.entries(
+    questionBank.skillLevels || {},
+  )) {
+    skillStats[skillId] = {};
+    for (const level of SKILL_LEVELS) {
+      skillStats[skillId][level] = (levels[level] || []).length;
+    }
+    skillStats[skillId].total = Object.values(skillStats[skillId]).reduce(
+      (a, b) => a + b,
+      0,
+    );
+  }
+
+  const behaviourStats = {};
+  for (const [behaviourId, maturities] of Object.entries(
+    questionBank.behaviourMaturities || {},
+  )) {
+    behaviourStats[behaviourId] = {};
+    for (const maturity of BEHAVIOUR_MATURITIES) {
+      behaviourStats[behaviourId][maturity] = (
+        maturities[maturity] || []
+      ).length;
+    }
+    behaviourStats[behaviourId].total = Object.values(
+      behaviourStats[behaviourId],
+    ).reduce((a, b) => a + b, 0);
+  }
+
+  return {
+    totalQuestions: questions.length,
+    bySource,
+    byLevel,
+    skillStats,
+    behaviourStats,
+  };
+}
+
+/**
+ * Prepare questions view for rendering
+ * @param {Object} params
+ * @param {Object} params.questionBank
+ * @param {Array} params.skills
+ * @param {Array} params.behaviours
+ * @param {QuestionsFilter} params.filter
+ * @returns {QuestionsView}
+ */
+export function prepareQuestionsView({
+  questionBank,
+  skills,
+  behaviours,
+  filter,
+}) {
+  const questions = flattenQuestions(questionBank, skills, behaviours, filter);
+  const stats = calculateStats(questions, questionBank);
+
+  return {
+    filter,
+    questions,
+    stats,
+  };
+}

package/app/formatters/questions/yaml.js

@@ -0,0 +1,76 @@
+/**
+ * Questions YAML Formatter
+ *
+ * Formats questions as YAML for export and bulk editing.
+ */
+
+import { stringify } from "yaml";
+
+/**
+ * Format questions as YAML
+ * @param {Object} view - Questions view from prepareQuestionsView
+ * @param {Object} options - Format options
+ * @returns {string}
+ */
+export function questionsToYaml(view, _options = {}) {
+  const { filter, questions } = view;
+
+  // Build header comment
+  const filterParts = [];
+  if (filter.level) filterParts.push(`--level=${filter.level}`);
+  if (filter.maturity) filterParts.push(`--maturity=${filter.maturity}`);
+  if (filter.skills) filterParts.push(`--skill=${filter.skills.join(",")}`);
+  if (filter.behaviours)
+    filterParts.push(`--behaviour=${filter.behaviours.join(",")}`);
+  if (filter.capability) filterParts.push(`--capability=${filter.capability}`);
+
+  const filterStr =
+    filterParts.length > 0 ? filterParts.join(" ") : "(no filters)";
+  const header = `# Generated by: npx pathway questions ${filterStr}\n# Questions: ${questions.length}\n\n`;
+
+  // Group questions by source
+  const bySource = {};
+  for (const q of questions) {
+    if (!bySource[q.source]) {
+      bySource[q.source] = [];
+    }
+
+    // Build question object for YAML
+    const yamlQuestion = {
+      id: q.id,
+      text: q.text,
+      lookingFor: q.lookingFor,
+      expectedDurationMinutes: q.expectedDurationMinutes,
+    };
+
+    if (q.followUps.length > 0) {
+      yamlQuestion.followUps = q.followUps;
+    }
+
+    bySource[q.source].push({
+      level: q.level,
+      question: yamlQuestion,
+    });
+  }
+
+  // Build output structure grouped by source then level
+  const output = {};
+  for (const [sourceId, items] of Object.entries(bySource).sort()) {
+    output[sourceId] = {};
+    for (const item of items) {
+      if (!output[sourceId][item.level]) {
+        output[sourceId][item.level] = [];
+      }
+      output[sourceId][item.level].push(item.question);
+    }
+  }
+
+  // Stringify with nice formatting
+  const yamlContent = stringify(output, {
+    lineWidth: 80,
+    defaultKeyType: "PLAIN",
+    defaultStringType: "PLAIN",
+  });
+
+  return header + yamlContent;
+}