@hippo-digital/hippocampus 1.0.0-rc.1

package/lib/resolve-root.js

@@ -0,0 +1,84 @@
+const fs = require('fs')
+const path = require('path')
+
+const CONFIG_FILENAME = 'hippocampus.config.json'
+
+// Where is the host project? Everything else - which knowledge base to read,
+// where drafts land, where artefacts are written - hangs off this one answer,
+// and a silently wrong answer produces an empty knowledge base with no
+// explanation. So the precedence is explicit, the chosen source is reported,
+// and a root inside node_modules is a hard error rather than a guess.
+//
+//   --root <dir>  >  HIPPOCAMPUS_ROOT  >  nearest ancestor with
+//   hippocampus.config.json  >  nearest ancestor with package.json  >  cwd
+
+function readArgRoot (argv) {
+  const flagIndex = argv.indexOf('--root')
+  if (flagIndex !== -1 && argv[flagIndex + 1] && !argv[flagIndex + 1].startsWith('--')) {
+    return argv[flagIndex + 1]
+  }
+  const inline = argv.find((arg) => arg.startsWith('--root='))
+  return inline ? inline.slice('--root='.length) : null
+}
+
+function isInsideNodeModules (dir) {
+  return path.resolve(dir).split(path.sep).includes('node_modules')
+}
+
+function nearestAncestor (start, predicate) {
+  let dir = path.resolve(start)
+  for (;;) {
+    if (!isInsideNodeModules(dir) && predicate(dir)) return dir
+    const parent = path.dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+function resolveRoot ({
+  argv = process.argv.slice(2),
+  env = process.env,
+  cwd = process.cwd()
+} = {}) {
+  const argRoot = readArgRoot(argv)
+  const envRoot = env.HIPPOCAMPUS_ROOT || null
+
+  let root
+  let source
+
+  if (argRoot) {
+    root = path.resolve(cwd, argRoot)
+    source = '--root'
+  } else if (envRoot) {
+    root = path.resolve(cwd, envRoot)
+    source = 'HIPPOCAMPUS_ROOT'
+  } else {
+    const configured = nearestAncestor(cwd, (dir) => fs.existsSync(path.join(dir, CONFIG_FILENAME)))
+    const packaged = configured || nearestAncestor(cwd, (dir) => fs.existsSync(path.join(dir, 'package.json')))
+    root = packaged || path.resolve(cwd)
+    source = configured ? CONFIG_FILENAME : (packaged ? 'package.json' : 'cwd')
+  }
+
+  if (!fs.existsSync(root)) {
+    throw new Error(`Hippocampus root does not exist: ${root} (from ${source})`)
+  }
+
+  if (!fs.statSync(root).isDirectory()) {
+    throw new Error(`Hippocampus root is not a directory: ${root} (from ${source})`)
+  }
+
+  // The library ships inside the host's node_modules. If the root resolves in
+  // there, something has walked up from __dirname instead of from the host -
+  // and the symptom would be an empty knowledge base, not an error.
+  if (isInsideNodeModules(root)) {
+    throw new Error(
+      `Hippocampus root resolved inside node_modules: ${root} (from ${source}).\n` +
+      'This is the installed package, not your project. Run the command from your ' +
+      'project directory, or pass --root <project> / set HIPPOCAMPUS_ROOT.'
+    )
+  }
+
+  return { root, source, configPath: path.join(root, CONFIG_FILENAME) }
+}
+
+module.exports = { resolveRoot, CONFIG_FILENAME, isInsideNodeModules }

package/lib/schema-version.js

@@ -0,0 +1,96 @@
+const fs = require('fs')
+const path = require('path')
+
+// The data contract. Within a schemaVersion changes are additive only, and
+// unknown fields survive a read/write round trip (every record schema is
+// passthrough) - that pair is what actually makes data written by version N
+// readable by N+1 and back again. Anything non-additive bumps this number,
+// ships with a package major, and gets a migration below.
+const CURRENT_SCHEMA_VERSION = 1
+const META_FILENAME = '_meta.json'
+
+// Keyed by the version they migrate FROM. Empty on purpose: version 1 is the
+// first, and the runner exists so the first real migration is a data change
+// rather than an architecture change made under pressure.
+const migrations = {}
+
+function readMeta (knowledgeSourceDir) {
+  const metaPath = path.join(knowledgeSourceDir, META_FILENAME)
+  if (!fs.existsSync(metaPath)) {
+    // Absent means version 1 - every knowledge base written before _meta.json
+    // existed is a valid version 1 base, and inventing a file on read would
+    // make an unwritable directory fail for no reason.
+    return { schemaVersion: 1, implicit: true, metaPath }
+  }
+
+  let meta
+  try {
+    meta = JSON.parse(fs.readFileSync(metaPath, 'utf8'))
+  } catch (error) {
+    throw new Error(`${META_FILENAME} is not valid JSON: ${metaPath}\n${error.message}`)
+  }
+
+  const schemaVersion = Number(meta.schemaVersion)
+  if (!Number.isInteger(schemaVersion) || schemaVersion < 1) {
+    throw new Error(`${META_FILENAME} has no usable schemaVersion: ${metaPath}`)
+  }
+
+  return { ...meta, schemaVersion, implicit: false, metaPath }
+}
+
+/**
+ * Brings data up to the version this code understands, in memory.
+ *
+ * Data newer than the code is refused outright. Reading a file forward - "the
+ * fields I recognise are enough" - is how a knowledge base gets silently
+ * destroyed by the next write, and an error the day someone downgrades is far
+ * cheaper than losing a round of research quietly.
+ */
+function migrateInMemory (knowledge, meta) {
+  if (meta.schemaVersion > CURRENT_SCHEMA_VERSION) {
+    throw new Error(
+      `This knowledge base is at schemaVersion ${meta.schemaVersion}, but this ` +
+      `version of Hippocampus understands ${CURRENT_SCHEMA_VERSION}.\n` +
+      `${meta.metaPath}\nUpgrade the package rather than reading it with older code.`
+    )
+  }
+
+  const warnings = []
+  let data = knowledge
+  let version = meta.schemaVersion
+
+  while (version < CURRENT_SCHEMA_VERSION) {
+    const migrate = migrations[version]
+    if (!migrate) {
+      throw new Error(`No migration from schemaVersion ${version} to ${version + 1}`)
+    }
+    data = migrate(data)
+    version += 1
+    warnings.push(
+      `Knowledge base read as schemaVersion ${version - 1} and migrated to ${version} in memory. ` +
+      'Run `npm run migrate:knowledge` to write the upgrade back.'
+    )
+  }
+
+  return { data, version, warnings }
+}
+
+function writeMeta (knowledgeSourceDir, { generator } = {}) {
+  const metaPath = path.join(knowledgeSourceDir, META_FILENAME)
+  const meta = {
+    schemaVersion: CURRENT_SCHEMA_VERSION,
+    generator: generator || 'hippocampus',
+    updatedAt: new Date().toISOString()
+  }
+  fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2) + '\n')
+  return meta
+}
+
+module.exports = {
+  CURRENT_SCHEMA_VERSION,
+  META_FILENAME,
+  migrations,
+  readMeta,
+  migrateInMemory,
+  writeMeta
+}

package/lib/schema.js

@@ -0,0 +1,346 @@
+const { z } = require('zod')
+
+const id = z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, 'Use lowercase kebab-case IDs')
+const nonEmptyString = z.string().trim().min(1)
+const stringList = z.array(nonEmptyString).min(1)
+
+const ProjectSchema = z.object({
+  id,
+  name: nonEmptyString,
+  description: nonEmptyString,
+  phase: nonEmptyString,
+  serviceArea: nonEmptyString,
+  prototypeSlice: id
+}).passthrough()
+
+const ProjectContextUserSchema = z.object({
+  id,
+  label: nonEmptyString,
+  group: nonEmptyString.optional(),
+  description: nonEmptyString.optional()
+}).passthrough()
+
+const ProjectContextChannelSchema = z.object({
+  id,
+  label: nonEmptyString,
+  description: nonEmptyString.optional(),
+  usage: nonEmptyString.optional()
+}).passthrough()
+
+const ProjectContextPolicySchema = z.object({
+  id,
+  title: nonEmptyString,
+  summary: nonEmptyString.optional(),
+  sourceUrl: nonEmptyString.optional()
+}).passthrough()
+
+const ProjectContextConstraintSchema = z.object({
+  id,
+  label: nonEmptyString,
+  detail: nonEmptyString,
+  impact: nonEmptyString.optional()
+}).passthrough()
+
+const ProjectContextRiskSchema = z.object({
+  id,
+  label: nonEmptyString,
+  detail: nonEmptyString.optional(),
+  severity: z.enum(['high', 'medium', 'low']).optional()
+}).passthrough()
+
+const ProjectContextMilestoneSchema = z.object({
+  id,
+  label: nonEmptyString,
+  date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'Use YYYY-MM-DD dates').optional(),
+  detail: nonEmptyString.optional()
+}).passthrough()
+
+const ProjectContextFactSchema = z.object({
+  id,
+  label: nonEmptyString,
+  value: nonEmptyString,
+  detail: nonEmptyString.optional()
+}).passthrough()
+
+const ProjectContextArtefactSchema = z.object({
+  id,
+  title: nonEmptyString,
+  sourcePath: nonEmptyString,
+  sourceType: nonEmptyString,
+  importedAt: nonEmptyString.optional()
+}).passthrough()
+
+const ProjectContextSchema = z.object({
+  id,
+  title: nonEmptyString,
+  summary: nonEmptyString,
+  purpose: nonEmptyString.optional(),
+  vision: nonEmptyString.optional(),
+  problemStatement: nonEmptyString.optional(),
+  serviceProposition: nonEmptyString.optional(),
+  users: z.array(ProjectContextUserSchema).default([]),
+  channels: z.array(ProjectContextChannelSchema).default([]),
+  policies: z.array(ProjectContextPolicySchema).default([]),
+  constraints: z.array(ProjectContextConstraintSchema).default([]),
+  risks: z.array(ProjectContextRiskSchema).default([]),
+  milestones: z.array(ProjectContextMilestoneSchema).default([]),
+  facts: z.array(ProjectContextFactSchema).default([]),
+  sourceArtefacts: z.array(ProjectContextArtefactSchema).default([])
+}).passthrough()
+
+const UserSchema = z.object({
+  id,
+  label: nonEmptyString,
+  description: nonEmptyString,
+  responsibilities: stringList,
+  accessNeeds: stringList
+}).passthrough()
+
+const NeedSchema = z.object({
+  id,
+  userId: id,
+  statement: nonEmptyString,
+  priority: z.enum(['high', 'medium', 'low']),
+  evidenceIds: z.array(id).min(1),
+  reference: nonEmptyString.optional()
+}).passthrough()
+
+const LocationSearchSchema = z.object({
+  primaryIntent: nonEmptyString,
+  searchScope: z.enum(['household', 'postcode-area', 'both']),
+  triggerConditions: stringList,
+  availableInformation: stringList,
+  addressRole: nonEmptyString,
+  learnedFromResidents: stringList,
+  currentAndHistoricResidents: stringList,
+  outcomes: stringList,
+  risks: stringList
+}).passthrough()
+
+const ScenarioSchema = z.object({
+  id,
+  title: nonEmptyString,
+  userId: id,
+  trigger: nonEmptyString,
+  context: nonEmptyString,
+  riskLevel: z.enum(['high', 'medium', 'low']),
+  needIds: z.array(id).min(1),
+  happyPath: stringList,
+  edgeCases: stringList,
+  locationSearch: LocationSearchSchema.optional()
+}).passthrough()
+
+const PainPointSchema = z.object({
+  id,
+  label: nonEmptyString,
+  severity: z.enum(['high', 'medium', 'low'])
+}).passthrough()
+
+const JourneyStepSchema = z.object({
+  id,
+  label: nonEmptyString,
+  channel: z.enum(['app', 'staff', 'external', 'hybrid']),
+  userAction: nonEmptyString,
+  frontstage: stringList,
+  backstage: stringList,
+  supportProcesses: stringList,
+  dataDependencies: stringList,
+  securityAndGovernance: stringList,
+  painPoints: z.array(PainPointSchema),
+  exceptionHandling: stringList,
+  futureState: stringList.optional(),
+  needIds: z.array(id).min(1),
+  screenIds: z.array(id),
+  evidenceIds: z.array(id).min(1),
+  decisionIds: z.array(id)
+}).passthrough()
+
+const JourneySchema = z.object({
+  id,
+  title: nonEmptyString,
+  description: nonEmptyString,
+  scenarioId: id,
+  entryPoint: nonEmptyString,
+  exitPoint: nonEmptyString,
+  steps: z.array(JourneyStepSchema).min(1)
+}).passthrough()
+
+const ScreenSchema = z.object({
+  id,
+  route: z.string().regex(/^\/[a-z0-9][a-z0-9\-\/]*$/, 'Routes must be absolute lowercase paths'),
+  title: nonEmptyString,
+  purpose: nonEmptyString,
+  needIds: z.array(id).min(1),
+  components: stringList,
+  // A screen in the real NCRS prototype rather than in this viewer. The
+  // knowledge base models the service, not only the screens this repo happens
+  // to render, so the route smoke test skips these instead of failing on them.
+  external: z.boolean().optional(),
+  sourcePath: nonEmptyString.optional()
+}).passthrough()
+
+const EvidenceSchema = z.object({
+  id,
+  title: nonEmptyString,
+  sourceType: nonEmptyString,
+  summary: nonEmptyString,
+  confidence: z.enum(['high', 'medium', 'low']),
+  sourcePath: nonEmptyString.optional(),
+  quotes: z.array(nonEmptyString).optional()
+}).passthrough()
+
+const DecisionSchema = z.object({
+  id,
+  title: nonEmptyString,
+  status: z.enum(['proposed', 'accepted', 'superseded', 'rejected']),
+  decision: nonEmptyString,
+  consequence: nonEmptyString
+}).passthrough()
+
+const AssumptionSchema = z.object({
+  id,
+  statement: nonEmptyString,
+  risk: z.enum(['high', 'medium', 'low'])
+}).passthrough()
+
+const ResearchRoundSchema = z.object({
+  id,
+  title: nonEmptyString,
+  date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'Use YYYY-MM-DD dates'),
+  sourceType: nonEmptyString,
+  sourcePath: nonEmptyString.optional(),
+  summary: nonEmptyString
+}).passthrough()
+
+const ParticipantSchema = z.object({
+  id,
+  label: nonEmptyString,
+  role: nonEmptyString,
+  organisation: nonEmptyString.optional(),
+  roundIds: z.array(id).min(1)
+}).passthrough()
+
+const InsightSchema = z.object({
+  id,
+  roundId: id,
+  title: nonEmptyString,
+  summary: nonEmptyString,
+  confidence: z.enum(['high', 'medium', 'low']),
+  participantIds: z.array(id),
+  evidenceIds: z.array(id)
+}).passthrough()
+
+const DesignActionSchema = z.object({
+  id,
+  title: nonEmptyString,
+  status: z.enum(['proposed', 'in-progress', 'done', 'parked']),
+  action: nonEmptyString,
+  rationale: nonEmptyString,
+  insightIds: z.array(id).min(1)
+}).passthrough()
+
+const RelationshipSchema = z.object({
+  id,
+  from: id,
+  type: z.enum([
+    'has-scenario',
+    'has-need',
+    'tests-need',
+    'supported-by',
+    'drives-journey',
+    'renders-screen',
+    'addresses-need',
+    'uses-evidence',
+    'records-decision',
+    'has-participant',
+    'produced-insight',
+    'contributed-to',
+    'supports-insight',
+    // Dependents point at what they rely on, because evidence impact walks
+    // relationship.to -> relationship.from. A design action relies on the
+    // insight that prompted it, and a decision relies on the action it
+    // resolves, so both point backwards down the chain. Written the other way
+    // round the impact walk stops at the insight, which is exactly where the
+    // question "if this research is wrong, what design work is affected?"
+    // becomes worth asking.
+    'responds-to-insight',
+    'resolves-action',
+    // Retained so older drafts still validate. New links use
+    // responds-to-insight, which traces.
+    'leads-to-action'
+  ]),
+  to: id
+}).passthrough()
+
+const ResearchImportDraftSchema = z.object({
+  sourceDeck: nonEmptyString,
+  importedAt: nonEmptyString,
+  warnings: z.array(nonEmptyString).optional(),
+  researchRounds: z.array(ResearchRoundSchema).min(1),
+  participants: z.array(ParticipantSchema).default([]),
+  insights: z.array(InsightSchema).default([]),
+  designActions: z.array(DesignActionSchema).default([]),
+  relationships: z.array(RelationshipSchema).default([]),
+  slides: z.array(z.object({
+    number: z.number().int().positive(),
+    title: nonEmptyString,
+    text: z.array(nonEmptyString)
+  }).strict()).min(1)
+}).strict()
+
+const ProjectContextImportDraftSchema = z.object({
+  sourceDocument: nonEmptyString,
+  importedAt: nonEmptyString,
+  warnings: z.array(nonEmptyString).optional(),
+  projectContext: ProjectContextSchema,
+  sections: z.array(z.object({
+    number: z.number().int().positive(),
+    title: nonEmptyString,
+    text: z.array(nonEmptyString)
+  }).strict()).min(1)
+}).strict()
+
+const KnowledgeSchema = z.object({
+  project: ProjectSchema,
+  projectContext: ProjectContextSchema,
+  users: z.array(UserSchema).default([]),
+  needs: z.array(NeedSchema).default([]),
+  scenarios: z.array(ScenarioSchema).default([]),
+  journeys: z.array(JourneySchema).default([]),
+  screens: z.array(ScreenSchema).default([]),
+  evidence: z.array(EvidenceSchema).default([]),
+  decisions: z.array(DecisionSchema).default([]),
+  assumptions: z.array(AssumptionSchema).default([]),
+  researchRounds: z.array(ResearchRoundSchema).default([]),
+  participants: z.array(ParticipantSchema).default([]),
+  insights: z.array(InsightSchema).default([]),
+  designActions: z.array(DesignActionSchema).default([]),
+  relationships: z.array(RelationshipSchema).default([])
+}).strict()
+
+// Exported so the linter can tell a deliberate extra field from a typo. Record
+// schemas are passthrough, which is what lets data written by a slightly newer
+// package round-trip; the cost is that `titel` no longer fails the parse, so the
+// linter has to notice it instead.
+const recordSchemas = {
+  users: UserSchema,
+  needs: NeedSchema,
+  scenarios: ScenarioSchema,
+  journeys: JourneySchema,
+  screens: ScreenSchema,
+  evidence: EvidenceSchema,
+  decisions: DecisionSchema,
+  assumptions: AssumptionSchema,
+  researchRounds: ResearchRoundSchema,
+  participants: ParticipantSchema,
+  insights: InsightSchema,
+  designActions: DesignActionSchema,
+  relationships: RelationshipSchema
+}
+
+module.exports = {
+  KnowledgeSchema,
+  ResearchImportDraftSchema,
+  ProjectContextImportDraftSchema,
+  recordSchemas
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@hippo-digital/hippocampus",
+  "version": "1.0.0-rc.1",
+  "description": "A design-knowledge base for NHS Prototype Kit projects: research, insights, needs, journeys and screens, traceable end to end.",
+  "license": "MIT",
+  "main": "index.js",
+  "bin": {
+    "hippocampus": "bin/hippocampus.js"
+  },
+  "files": [
+    "index.js",
+    "bin",
+    "lib",
+    "views",
+    "assets",
+    "scripts",
+    "skills",
+    "templates",
+    "docs",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build:assets": "sass --no-source-map --style=compressed assets/hippocampus.scss assets/dist/hippocampus.css",
+    "validate:skills": "node scripts/validate-skills.js",
+    "prepack": "npm run build:assets",
+    "prepublishOnly": "node ../../scripts/check-release.js"
+  },
+  "dependencies": {
+    "adm-zip": "^0.5.18",
+    "fast-xml-parser": "^5.9.3",
+    "marked": "^18.0.13",
+    "pdf-parse": "^2.4.5",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "sass": "^1.80.0"
+  },
+  "peerDependencies": {
+    "nhsuk-frontend": ">=10.5.1",
+    "nhsuk-prototype-kit": ">=8.3.0"
+  },
+  "engines": {
+    "node": ">=22.16.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hippo-digital/nhs-prototype-hippocampus.git",
+    "directory": "packages/hippocampus"
+  },
+  "homepage": "https://github.com/hippo-digital/nhs-prototype-hippocampus/tree/main/packages/hippocampus#readme",
+  "bugs": {
+    "url": "https://github.com/hippo-digital/nhs-prototype-hippocampus/issues"
+  },
+  "keywords": [
+    "nhs",
+    "nhsuk",
+    "prototype-kit",
+    "design",
+    "user-research",
+    "knowledge-base",
+    "service-design",
+    "accessibility"
+  ],
+  "author": "Hippo Digital",
+  "publishConfig": {
+    "access": "public"
+  }
+}