@forwardimpact/map 0.11.1 → 0.13.0

package/README.md

@@ -64,4 +64,4 @@ examples/
 └── questions/            # Interview questions
 ```
 
-See the [documentation](../../docs/map/index.md) for details.
+See the [documentation](../../website/docs/map/index.md) for details.

package/bin/fit-map.js

@@ -3,11 +3,12 @@
 /**
  * fit-map CLI
  *
- * Map validation and index generation for Engineering Pathway data.
+ * Map validation, index generation, and activity management for Engineering Pathway data.
  *
  * Commands:
  *   validate [--json|--shacl]   Run validation (default: --json)
  *   generate-index [--data=PATH] Generate _index.yaml files
+ *   people import <file>        Import people from CSV/YAML
  *   --help                      Show help
  */
 
@@ -22,22 +23,29 @@ const __dirname = dirname(__filename);
  * Parse CLI arguments
  */
 function parseArgs(args) {
-  const command = args[0];
   const options = {};
-
-  for (let i = 1; i < args.length; i++) {
-    const arg = args[i];
-    if (arg.startsWith("--data=")) {
-      options.dataDir = arg.slice(7);
-    } else if (arg === "--help" || arg === "-h") {
+  const positional = [];
+
+  for (const arg of args) {
+    if (arg.startsWith("--")) {
+      if (arg === "--help") {
+        options.help = true;
+      } else {
+        const [key, value] = arg.slice(2).split("=");
+        options[key] = value ?? true;
+      }
+    } else if (arg === "-h") {
       options.help = true;
-    } else if (arg.startsWith("--")) {
-      const [key, value] = arg.slice(2).split("=");
-      options[key] = value ?? true;
+    } else {
+      positional.push(arg);
     }
   }
 
-  return { command, options };
+  const command = positional[0] || null;
+  const subcommand = positional[1] || null;
+  const rest = positional.slice(2);
+
+  return { command, subcommand, options, positional: rest };
 }
 
 /**
@@ -64,11 +72,11 @@ async function findDataDir(providedPath) {
     throw new Error(`Data directory not found: ${providedPath}`);
   }
 
-  // Check common locations
   const candidates = [
+    join(process.cwd(), "data/pathway"),
+    join(process.cwd(), "examples/pathway"),
     join(process.cwd(), "data"),
     join(process.cwd(), "examples"),
-    join(__dirname, "../examples"),
   ];
 
   for (const candidate of candidates) {
@@ -116,17 +124,17 @@ function formatValidationResults(result) {
 async function runValidate(dataDir) {
   console.log(`🔍 Validating data in: ${dataDir}\n`);
 
-  const { runSchemaValidation, loadAllData } = await import("../src/index.js");
+  const { createDataLoader, createSchemaValidator } =
+    await import("../src/index.js");
 
-  // Load data first
-  const data = await loadAllData(dataDir, { validate: false });
+  const loader = createDataLoader();
+  const validator = createSchemaValidator();
 
-  // Run full validation
-  const result = await runSchemaValidation(dataDir, data);
+  const data = await loader.loadAllData(dataDir);
+  const result = await validator.runFullValidation(dataDir, data);
 
   console.log(formatValidationResults(result));
 
-  // Print summary
   console.log("\n📊 Data Summary:");
   console.log(`   Skills:      ${data.skills?.length || 0}`);
   console.log(`   Behaviours:  ${data.behaviours?.length || 0}`);
@@ -144,9 +152,10 @@ async function runValidate(dataDir) {
 async function runGenerateIndex(dataDir) {
   console.log(`📁 Generating index files in: ${dataDir}\n`);
 
-  const { generateAllIndexes } = await import("../src/index.js");
+  const { createIndexGenerator } = await import("../src/index.js");
 
-  const results = await generateAllIndexes(dataDir);
+  const generator = createIndexGenerator();
+  const results = await generator.generateAllIndexes(dataDir);
 
   for (const [dir, files] of Object.entries(results)) {
     if (files.error) {
@@ -171,7 +180,6 @@ async function runValidateShacl() {
     const { default: N3 } = await import("n3");
     const { readFile, readdir } = await import("fs/promises");
 
-    // Find all .ttl files in the RDF directory
     const files = await readdir(rdfDir);
     const ttlFiles = files.filter((f) => f.endsWith(".ttl")).sort();
 
@@ -214,31 +222,62 @@ async function runValidateShacl() {
   }
 }
 
+/**
+ * People import command
+ */
+async function runPeopleImport(filePath, dataDir) {
+  console.log(`👤 Importing people from: ${filePath}\n`);
+
+  const { loadPeopleFile, validatePeople } =
+    await import("../activity/transform/people.js");
+
+  const people = await loadPeopleFile(filePath);
+  console.log(`  Loaded ${people.length} people from file`);
+
+  const { valid, errors } = await validatePeople(people, dataDir);
+
+  if (errors.length > 0) {
+    console.log(`\n❌ Validation errors:`);
+    for (const err of errors) {
+      console.log(`  • Row ${err.row}: ${err.message}`);
+    }
+  }
+
+  console.log(`\n✅ ${valid.length} people validated`);
+  if (errors.length > 0) {
+    console.log(`❌ ${errors.length} rows with errors\n`);
+  }
+
+  return errors.length > 0 ? 1 : 0;
+}
+
 /**
  * Show help
  */
 function showHelp() {
   console.log(`
-fit-map - Data validation for Engineering Pathway
+fit-map - Data validation and management for Engineering Pathway
 
 Usage:
   fit-map <command> [options]
 
 Commands:
-  validate           Run validation (default: JSON schema validation)
-  generate-index     Generate _index.yaml files for directories
+  validate              Run validation (default: JSON schema validation)
+  generate-index        Generate _index.yaml files for directories
+  people import <file>  Import people from CSV/YAML (validates against framework)
 
 Options:
-  --json             JSON schema + referential validation (default)
-  --shacl            SHACL schema syntax validation
-  --data=PATH        Path to data directory (default: ./data or ./examples)
-  --help, -h         Show this help message
+  --json                JSON schema + referential validation (default)
+  --shacl               SHACL schema syntax validation
+  --data=PATH           Path to data directory (default: ./data or ./examples)
+  --help, -h            Show this help message
 
 Examples:
   fit-map validate
   fit-map validate --shacl
   fit-map validate --data=./my-data
   fit-map generate-index
+  fit-map people import ./org/people.yaml
 `);
 }
 
@@ -246,11 +285,13 @@ Examples:
  * Main entry point
  */
 async function main() {
-  const { command, options } = parseArgs(process.argv.slice(2));
+  const { command, subcommand, options, positional } = parseArgs(
+    process.argv.slice(2),
+  );
 
   if (options.help || !command) {
     showHelp();
-    process.exit(command ? 0 : 1);
+    process.exit(options.help ? 0 : 1);
   }
 
   try {
@@ -261,16 +302,32 @@ async function main() {
         if (options.shacl) {
           exitCode = await runValidateShacl();
         } else {
-          const dataDir = await findDataDir(options.dataDir);
+          const dataDir = await findDataDir(options.data);
           exitCode = await runValidate(dataDir);
         }
         break;
       }
       case "generate-index": {
-        const dataDir = await findDataDir(options.dataDir);
+        const dataDir = await findDataDir(options.data);
         exitCode = await runGenerateIndex(dataDir);
         break;
       }
+      case "people": {
+        if (subcommand === "import") {
+          const filePath = positional[0];
+          if (!filePath) {
+            console.error("Error: people import requires a file path");
+            process.exit(1);
+          }
+          const dataDir = await findDataDir(options.data);
+          exitCode = await runPeopleImport(filePath, dataDir);
+        } else {
+          console.error(`Unknown people subcommand: ${subcommand || "(none)"}`);
+          showHelp();
+          exitCode = 1;
+        }
+        break;
+      }
       default:
         console.error(`Unknown command: ${command}`);
         showHelp();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/map",
-  "version": "0.11.1",
+  "version": "0.13.0",
   "description": "Public data model for career frameworks, consumed by AI agents and engineers",
   "license": "Apache-2.0",
   "repository": {
@@ -20,7 +20,6 @@
   },
   "files": [
     "bin/",
-    "examples/",
     "src/",
     "schema/"
   ],
@@ -31,9 +30,20 @@
     "./schema-validation": "./src/schema-validation.js",
     "./index-generator": "./src/index-generator.js",
     "./levels": "./src/levels.js",
-    "./examples/*": "./examples/*",
     "./schema/json/*": "./schema/json/*",
-    "./schema/rdf/*": "./schema/rdf/*"
+    "./schema/rdf/*": "./schema/rdf/*",
+    "./activity/queries/org": "./activity/queries/org.js",
+    "./activity/queries/snapshots": "./activity/queries/snapshots.js",
+    "./activity/queries/evidence": "./activity/queries/evidence.js",
+    "./activity/queries/artifacts": "./activity/queries/artifacts.js",
+    "./activity/storage": "./activity/storage.js",
+    "./activity/extract/github": "./activity/extract/github.js",
+    "./activity/extract/getdx": "./activity/extract/getdx.js",
+    "./activity/extract/people": "./activity/extract/people.js",
+    "./activity/transform/github": "./activity/transform/github.js",
+    "./activity/transform/getdx": "./activity/transform/getdx.js",
+    "./activity/transform/people": "./activity/transform/people.js",
+    "./activity/transform": "./activity/transform/index.js"
   },
   "dependencies": {
     "ajv": "^8.17.1",

package/schema/json/capability.schema.json

@@ -105,10 +105,43 @@
         "implementationReference": {
           "type": "string",
           "description": "Code examples and detailed reference material, exported to references/REFERENCE.md"
+        },
+        "markers": {
+          "$ref": "#/$defs/skillMarkers",
+          "description": "Observable indicators of skill proficiency, keyed by level"
         }
       },
       "additionalProperties": false
     },
+    "skillMarkers": {
+      "type": "object",
+      "description": "Observable indicators of skill proficiency, keyed by level",
+      "propertyNames": {
+        "enum": [
+          "awareness",
+          "foundational",
+          "working",
+          "practitioner",
+          "expert"
+        ]
+      },
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "human": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Observable markers for human engineers"
+          },
+          "agent": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Observable markers for AI agents"
+          }
+        },
+        "additionalProperties": false
+      }
+    },
     "toolReference": {
       "type": "object",
       "required": ["name", "description", "useWhen"],

package/schema/json/discipline.schema.json

@@ -88,13 +88,9 @@
     "disciplineHumanSection": {
       "type": "object",
       "properties": {
-        "professionalRoleSummary": {
+        "roleSummary": {
           "type": "string",
-          "description": "Role summary for professional/IC track. May use {roleTitle} placeholder."
-        },
-        "managementRoleSummary": {
-          "type": "string",
-          "description": "Role summary for management track. May use {specialization} placeholder."
+          "description": "Role summary for this discipline. May use {roleTitle} or {specialization} placeholder."
         }
       },
       "additionalProperties": false

package/schema/rdf/capability.ttl

@@ -38,6 +38,10 @@ fit:ToolReference a rdfs:Class ;
     rdfs:label "Tool Reference"@en ;
     rdfs:comment "Reference to an external tool with usage guidance"@en .
 
+fit:SkillMarkers a rdfs:Class ;
+    rdfs:label "Skill Markers"@en ;
+    rdfs:comment "Observable indicators of skill proficiency at a level"@en .
+
 # -----------------------------------------------------------------------------
 # Properties
 # -----------------------------------------------------------------------------
@@ -95,6 +99,24 @@ fit:implementationReference a rdf:Property ;
     rdfs:domain fit:Skill ;
     rdfs:range xsd:string .
 
+fit:markers a rdf:Property ;
+    rdfs:label "markers"@en ;
+    rdfs:comment "Observable indicators keyed by proficiency level"@en ;
+    rdfs:domain fit:Skill ;
+    rdfs:range fit:SkillMarkers .
+
+fit:humanMarkers a rdf:Property ;
+    rdfs:label "humanMarkers"@en ;
+    rdfs:comment "Observable markers for human engineers"@en ;
+    rdfs:domain fit:SkillMarkers ;
+    rdfs:range xsd:string .
+
+fit:agentMarkers a rdf:Property ;
+    rdfs:label "agentMarkers"@en ;
+    rdfs:comment "Observable markers for AI agents"@en ;
+    rdfs:domain fit:SkillMarkers ;
+    rdfs:range xsd:string .
+
 fit:toolReferences a rdf:Property ;
     rdfs:label "toolReferences"@en ;
     rdfs:comment "Required tools for this skill"@en ;
@@ -315,6 +337,32 @@ fit:SkillShape a sh:NodeShape ;
         sh:maxCount 1 ;
         sh:name "implementationReference" ;
         sh:description "Code examples and detailed reference material, exported to references/REFERENCE.md" ;
+    ] ;
+    sh:property [
+        sh:path fit:markers ;
+        sh:node fit:SkillMarkersShape ;
+        sh:maxCount 1 ;
+        sh:name "markers" ;
+        sh:description "Observable indicators of skill proficiency, keyed by level" ;
+    ] .
+
+# -----------------------------------------------------------------------------
+# Skill Markers Shape
+# -----------------------------------------------------------------------------
+
+fit:SkillMarkersShape a sh:NodeShape ;
+    sh:targetClass fit:SkillMarkers ;
+    sh:property [
+        sh:path fit:humanMarkers ;
+        sh:datatype xsd:string ;
+        sh:name "human" ;
+        sh:description "Observable markers for human engineers" ;
+    ] ;
+    sh:property [
+        sh:path fit:agentMarkers ;
+        sh:datatype xsd:string ;
+        sh:name "agent" ;
+        sh:description "Observable markers for AI agents" ;
     ] .
 
 # -----------------------------------------------------------------------------

package/schema/rdf/discipline.ttl

@@ -86,15 +86,9 @@ fit:behaviourModifiers a rdf:Property ;
     rdfs:label "behaviourModifiers"@en ;
     rdfs:comment "Modifiers to behaviour expectations"@en .
 
-fit:professionalRoleSummary a rdf:Property ;
-    rdfs:label "professionalRoleSummary"@en ;
-    rdfs:comment "Role summary for professional/IC track. May use {roleTitle} placeholder."@en ;
-    rdfs:domain fit:DisciplineHumanSection ;
-    rdfs:range xsd:string .
-
-fit:managementRoleSummary a rdf:Property ;
-    rdfs:label "managementRoleSummary"@en ;
-    rdfs:comment "Role summary for management track. May use {specialization} placeholder."@en ;
+fit:roleSummary a rdf:Property ;
+    rdfs:label "roleSummary"@en ;
+    rdfs:comment "Role summary for this discipline. May use {roleTitle} or {specialization} placeholder."@en ;
     rdfs:domain fit:DisciplineHumanSection ;
     rdfs:range xsd:string .
 
@@ -244,18 +238,11 @@ fit:DisciplineShape a sh:NodeShape ;
 fit:DisciplineHumanSectionShape a sh:NodeShape ;
     sh:targetClass fit:DisciplineHumanSection ;
     sh:property [
-        sh:path fit:professionalRoleSummary ;
-        sh:datatype xsd:string ;
-        sh:maxCount 1 ;
-        sh:name "professionalRoleSummary" ;
-        sh:description "Role summary for professional/IC track" ;
-    ] ;
-    sh:property [
-        sh:path fit:managementRoleSummary ;
+        sh:path fit:roleSummary ;
         sh:datatype xsd:string ;
         sh:maxCount 1 ;
-        sh:name "managementRoleSummary" ;
-        sh:description "Role summary for management track" ;
+        sh:name "roleSummary" ;
+        sh:description "Role summary for this discipline" ;
     ] .
 
 # -----------------------------------------------------------------------------

package/src/index-generator.js

@@ -10,56 +10,85 @@ import { join, basename } from "path";
 import { stringify as stringifyYaml } from "yaml";
 
 /**
- * Generate _index.yaml for a directory
- * @param {string} dir - Directory path
- * @returns {Promise<string[]>} List of file IDs included
+ * Index generator class with injectable filesystem and serializer dependencies.
  */
-export async function generateDirIndex(dir) {
-  const files = await readdir(dir);
-  const yamlFiles = files.filter(
-    (f) => f.endsWith(".yaml") && !f.startsWith("_"),
-  );
+export class IndexGenerator {
+  #fs;
+  #yaml;
+
+  /**
+   * @param {{ readdir: Function, writeFile: Function }} fs
+   * @param {{ stringify: Function }} yamlSerializer
+   */
+  constructor(fs, yamlSerializer) {
+    if (!fs) throw new Error("fs is required");
+    if (!yamlSerializer) throw new Error("yamlSerializer is required");
+    this.#fs = fs;
+    this.#yaml = yamlSerializer;
+  }
 
-  const fileIds = yamlFiles.map((f) => basename(f, ".yaml")).sort();
+  /**
+   * Generate _index.yaml for a directory
+   * @param {string} dir - Directory path
+   * @returns {Promise<string[]>} List of file IDs included
+   */
+  async generateDirIndex(dir) {
+    const files = await this.#fs.readdir(dir);
+    const yamlFiles = files.filter(
+      (f) => f.endsWith(".yaml") && !f.startsWith("_"),
+    );
 
-  const content = stringifyYaml(
-    {
-      // Auto-generated index for browser loading
-      // Do not edit manually - regenerate with: npx pathway --generate-index
-      files: fileIds,
-    },
-    { lineWidth: 0 },
-  );
+    const fileIds = yamlFiles.map((f) => basename(f, ".yaml")).sort();
 
-  // Add header comment
-  const output = `# Auto-generated index for browser loading
+    const content = this.#yaml.stringify(
+      {
+        // Auto-generated index for browser loading
+        // Do not edit manually - regenerate with: npx pathway --generate-index
+        files: fileIds,
+      },
+      { lineWidth: 0 },
+    );
+
+    const output = `# Auto-generated index for browser loading
 # Do not edit manually - regenerate with: npx pathway --generate-index
 ${content}`;
 
-  await writeFile(join(dir, "_index.yaml"), output, "utf-8");
+    await this.#fs.writeFile(join(dir, "_index.yaml"), output, "utf-8");
 
-  return fileIds;
-}
+    return fileIds;
+  }
 
-/**
- * Generate all index files for the data directory
- * @param {string} dataDir - Path to the data directory
- * @returns {Promise<Object>} Summary of generated indexes
- */
-export async function generateAllIndexes(dataDir) {
-  const directories = ["behaviours", "disciplines", "tracks", "capabilities"];
+  /**
+   * Generate all index files for the data directory
+   * @param {string} dataDir - Path to the data directory
+   * @returns {Promise<Object>} Summary of generated indexes
+   */
+  async generateAllIndexes(dataDir) {
+    const directories = ["behaviours", "disciplines", "tracks", "capabilities"];
 
-  const results = {};
+    const results = {};
 
-  for (const dir of directories) {
-    const fullPath = join(dataDir, dir);
-    try {
-      const files = await generateDirIndex(fullPath);
-      results[dir] = files;
-    } catch (err) {
-      results[dir] = { error: err.message };
+    for (const dir of directories) {
+      const fullPath = join(dataDir, dir);
+      try {
+        const files = await this.generateDirIndex(fullPath);
+        results[dir] = files;
+      } catch (err) {
+        results[dir] = { error: err.message };
+      }
     }
+
+    return results;
   }
+}
 
-  return results;
+/**
+ * Create an IndexGenerator with real filesystem and serializer dependencies
+ * @returns {IndexGenerator}
+ */
+export function createIndexGenerator() {
+  return new IndexGenerator(
+    { readdir, writeFile },
+    { stringify: stringifyYaml },
+  );
 }

package/src/index.js

@@ -4,22 +4,17 @@
  * Data model definitions, validation, and loading for Engineering Pathway.
  */
 
-// Data loading
-export {
-  loadAllData,
-  loadYamlFile,
-  createDataLoader,
-  loadFrameworkConfig,
-  loadQuestionFolder,
-  loadQuestionBankFromFolder,
-  loadSelfAssessments,
-  loadExampleData,
-  loadAndValidate,
-  loadAgentData,
-  loadSkillsWithAgentData,
-} from "./loader.js";
+// Classes
+export { DataLoader } from "./loader.js";
+export { SchemaValidator } from "./schema-validation.js";
+export { IndexGenerator } from "./index-generator.js";
+
+// Factory functions
+export { createDataLoader } from "./loader.js";
+export { createSchemaValidator } from "./schema-validation.js";
+export { createIndexGenerator } from "./index-generator.js";
 
-// Referential integrity validation
+// Pure validation functions (unchanged)
 export {
   validateAllData,
   validateQuestionBank,
@@ -27,16 +22,6 @@ export {
   validateAgentData,
 } from "./validation.js";
 
-// Schema-based validation
-export {
-  validateDataDirectory,
-  validateReferentialIntegrity,
-  runSchemaValidation,
-} from "./schema-validation.js";
-
-// Index generation
-export { generateAllIndexes, generateDirIndex } from "./index-generator.js";
-
 // Type constants and helpers
 export * from "./levels.js";