@hippo-digital/hippocampus 1.0.0-rc.1

package/lib/docs.js

@@ -0,0 +1,72 @@
+const fs = require('fs')
+const path = require('path')
+const { marked } = require('marked')
+const packagePaths = require('./package-paths')
+
+// Docs are served, not copied.
+//
+// Eight guides copied into a host repo are stale within a release, and the
+// stale copy is the one people read - it is sitting in their editor, and the
+// current one is not. Serving them from the viewer means the documentation a
+// team reads always describes the version they have installed.
+//
+// Skills are the deliberate exception: an agent reads those as repo files, so
+// `hippocampus skills install` copies them, with hashes so an upgrade can tell
+// a stale copy from an edited one.
+
+const TITLE_OVERRIDES = {
+  'hippocampus-for-designers-and-researchers': 'Hippocampus for designers and researchers',
+  'gp-connect-real-data-to-production': 'GP Connect: real data to production'
+}
+
+function slugOf (filename) {
+  return filename.replace(/\.md$/, '')
+}
+
+function titleOf (filename, contents) {
+  const slug = slugOf(filename)
+  if (TITLE_OVERRIDES[slug]) return TITLE_OVERRIDES[slug]
+  const heading = contents.match(/^#\s+(.+)$/m)
+  if (heading) return heading[1].trim()
+  return slug.replace(/-/g, ' ').replace(/^./, (c) => c.toUpperCase())
+}
+
+function summaryOf (contents) {
+  const body = contents.replace(/^#\s+.+$/m, '').trim()
+  const paragraph = body.split(/\n\s*\n/).find((block) => block.trim() && !block.trim().startsWith('#'))
+  if (!paragraph) return ''
+  const text = paragraph.replace(/\s+/g, ' ').replace(/[*_`[\]]/g, '').trim()
+  return text.length > 200 ? `${text.slice(0, 197)}...` : text
+}
+
+function listDocs () {
+  if (!fs.existsSync(packagePaths.docsDir)) return []
+  return fs.readdirSync(packagePaths.docsDir)
+    .filter((name) => name.endsWith('.md'))
+    .sort()
+    .map((name) => {
+      const contents = fs.readFileSync(path.join(packagePaths.docsDir, name), 'utf8')
+      return { slug: slugOf(name), title: titleOf(name, contents), summary: summaryOf(contents) }
+    })
+}
+
+function readDoc (slug) {
+  // The slug comes off a URL, so it is checked against the directory listing
+  // rather than joined onto a path and hoped for.
+  if (!/^[a-z0-9-]+$/.test(slug)) return null
+  const filePath = path.join(packagePaths.docsDir, `${slug}.md`)
+  if (!fs.existsSync(filePath)) return null
+
+  const contents = fs.readFileSync(filePath, 'utf8')
+  return {
+    slug,
+    title: titleOf(`${slug}.md`, contents),
+    html: marked(contents, { mangle: false, headerIds: true })
+  }
+}
+
+function packageVersion () {
+  return require('../package.json').version
+}
+
+module.exports = { listDocs, readDoc, packageVersion }

package/lib/host-edit.js

@@ -0,0 +1,151 @@
+const crypto = require('crypto')
+const fs = require('fs')
+
+// Editing somebody else's app.js is the most dangerous thing this package does,
+// so the rules are narrow on purpose:
+//
+//   - every edit lives between markers, so it can be found and removed
+//   - the end marker carries a hash of the body, so a block somebody has
+//     customised is reported and left alone rather than silently overwritten
+//   - an insertion that does not match exactly once does nothing, and prints
+//     the lines to paste instead
+//
+// Half-editing a file leaves the owner worse off than not editing it and
+// telling them what to type.
+
+const START = (id) => `${id}:start v1 - managed by @hippo-digital/hippocampus`
+const END = (id, hash) => `${id}:end ${hash}`
+
+function hashBody (body) {
+  return crypto.createHash('sha256').update(body.trim()).digest('hex').slice(0, 12)
+}
+
+function markers (id, comment) {
+  const open = comment === 'js' ? '// >>> ' : '{# >>> '
+  const close = comment === 'js' ? '' : ' #}'
+  return {
+    start: `${open}${START(id)}${close}`,
+    endPrefix: comment === 'js' ? '// <<< ' : '{# <<< ',
+    endSuffix: close
+  }
+}
+
+function findBlock (source, id, comment = 'js') {
+  const { start, endPrefix } = markers(id, comment)
+  const startIndex = source.indexOf(start)
+  if (startIndex === -1) return null
+
+  const endMarkerIndex = source.indexOf(`${endPrefix}${id}:end`, startIndex)
+  if (endMarkerIndex === -1) {
+    return { startIndex, endIndex: -1, body: null, declaredHash: null, unterminated: true }
+  }
+
+  const endLineEnd = source.indexOf('\n', endMarkerIndex)
+  const endIndex = endLineEnd === -1 ? source.length : endLineEnd + 1
+  const body = source.slice(startIndex + start.length, endMarkerIndex)
+  const endLine = source.slice(endMarkerIndex, endLineEnd === -1 ? source.length : endLineEnd)
+  const declaredHash = (endLine.match(/:end\s+([0-9a-f]{12})/) || [])[1] || null
+
+  return { startIndex, endIndex, body, declaredHash, unterminated: false }
+}
+
+/**
+ * Result is one of:
+ *   { action: 'inserted' | 'updated' | 'unchanged', source }
+ *   { action: 'customised' | 'unterminated', reason }   - nothing written
+ */
+function upsertBlock (source, { id, body, comment = 'js', anchor }) {
+  const { start, endPrefix, endSuffix } = markers(id, comment)
+  const hash = hashBody(body)
+  const block = `${start}\n${body.trim()}\n${endPrefix}${id}:end ${hash}${endSuffix}\n`
+
+  const existing = findBlock(source, id, comment)
+
+  if (existing && existing.unterminated) {
+    return { action: 'unterminated', reason: `The ${id} block in this file has no end marker. Fix or remove it by hand.` }
+  }
+
+  if (existing) {
+    const currentHash = hashBody(existing.body)
+    if (existing.declaredHash && existing.declaredHash !== currentHash) {
+      return {
+        action: 'customised',
+        reason: `The ${id} block in this file has been edited since it was written. Leaving it alone.`
+      }
+    }
+    if (currentHash === hash) return { action: 'unchanged', source }
+    return {
+      action: 'updated',
+      source: source.slice(0, existing.startIndex) + block + source.slice(existing.endIndex)
+    }
+  }
+
+  const insertAt = anchor ? anchor(source) : null
+  if (insertAt === null || insertAt === undefined) {
+    return { action: 'no-anchor', reason: 'Could not find a safe place to insert this block.' }
+  }
+
+  return {
+    action: 'inserted',
+    source: source.slice(0, insertAt) + block + source.slice(insertAt)
+  }
+}
+
+function removeBlock (source, id, comment = 'js') {
+  const existing = findBlock(source, id, comment)
+  if (!existing || existing.unterminated) return { action: 'absent', source }
+  return {
+    action: 'removed',
+    source: source.slice(0, existing.startIndex) + source.slice(existing.endIndex)
+  }
+}
+
+/**
+ * Adds an entry to a simple array of string literals - the kit's viewsPath and
+ * entryPoints. Applied only when the pattern matches exactly once and the array
+ * contains nothing but string literals. Anything cleverer than that is somebody
+ * else's code doing something we do not understand, and we should not be
+ * rewriting it.
+ */
+function addToStringArray (source, { name, entry }) {
+  if (source.includes(entry)) return { action: 'unchanged', source }
+
+  const pattern = new RegExp(`(const\\s+${name}\\s*=\\s*\\[)([^\\]]*)\\]`, 'g')
+  const matches = [...source.matchAll(pattern)]
+  if (matches.length !== 1) {
+    return { action: 'no-anchor', reason: `Expected exactly one \`const ${name} = [...]\`, found ${matches.length}.` }
+  }
+
+  const [full, open, inner] = matches[0]
+  const items = inner.split(',').map((item) => item.trim()).filter(Boolean)
+  const allStringLiterals = items.every((item) => /^(['"]).*\1$/.test(item) || item.startsWith('//'))
+  if (!allStringLiterals) {
+    return { action: 'no-anchor', reason: `\`${name}\` is not a plain array of strings, so it is not safe to edit automatically.` }
+  }
+
+  const indent = (inner.match(/\n(\s+)/) || [, '  '])[1]
+  const replacement = `${open}${inner.replace(/\s*$/, '')},\n${indent}${entry}\n]`
+  return { action: 'updated', source: source.replace(full, replacement) }
+}
+
+function backup (filePath) {
+  const backupPath = `${filePath}.hippocampus-backup`
+  if (!fs.existsSync(backupPath)) fs.copyFileSync(filePath, backupPath)
+  return backupPath
+}
+
+function diff (before, after, filePath) {
+  const beforeLines = before.split('\n')
+  const afterLines = after.split('\n')
+  const out = [`--- ${filePath}`, `+++ ${filePath}`]
+  let i = 0
+  let j = 0
+  while (i < beforeLines.length || j < afterLines.length) {
+    if (beforeLines[i] === afterLines[j]) { i++; j++; continue }
+    if (afterLines.includes(beforeLines[i]) === false && i < beforeLines.length) { out.push(`-${beforeLines[i]}`); i++; continue }
+    out.push(`+${afterLines[j]}`); j++
+  }
+  return out.join('\n')
+}
+
+module.exports = { upsertBlock, removeBlock, addToStringArray, findBlock, hashBody, backup, diff }

package/lib/lint-knowledge.js

@@ -0,0 +1,133 @@
+const { recordSchemas } = require('./schema')
+
+// Parsing answers "is this loadable?". Linting answers the question a team
+// actually has: "what is thin, and what is missing?" Keeping them apart is what
+// lets a freshly initialised project boot with nothing in it while still being
+// told, every time, what it has not filled in yet.
+//
+//   error   - referential integrity. The graph is broken.
+//   warning - the old min-1 rules, rephrased as onboarding prompts, plus
+//             anything that looks like a mistake rather than a gap.
+//   info    - coverage. Nothing is wrong; something is thin.
+//
+// The info tier is the point. "51 insights have no need link" was something
+// somebody happened to notice once; it should be a line of standing output.
+
+const ONBOARDING = {
+  users: 'No users yet. Start with who the service is for - everything else hangs off a user.',
+  needs: 'No user needs yet. A need says who wants what, and why.',
+  scenarios: 'No scenarios yet. A scenario is the situation a user is in when a need bites.',
+  journeys: 'No journeys yet. A journey is how a scenario plays out, step by step.',
+  screens: 'No screens yet. A screen is a route this prototype serves, linked to the needs it meets.',
+  evidence: 'No evidence yet. Evidence is what makes a need a finding rather than an opinion.',
+  decisions: 'No decisions yet. A decision records an option that was weighed and what happened to it.',
+  assumptions: 'No assumptions yet. An assumption is a belief the design rests on that nobody has tested.'
+}
+
+function lintKnowledge (knowledge) {
+  const warnings = []
+  const infos = []
+  const index = knowledge.index || {}
+
+  for (const [collection, message] of Object.entries(ONBOARDING)) {
+    if (!(knowledge[collection] || []).length) {
+      warnings.push({ rule: 'empty-collection', collection, message })
+    }
+  }
+
+  // Passthrough schemas mean a misspelled key is kept rather than rejected.
+  // That is the right trade for forward compatibility, but somebody has to say
+  // "you wrote titel" or the field silently does nothing forever.
+  for (const [collection, schema] of Object.entries(recordSchemas)) {
+    const known = new Set(Object.keys(schema.shape))
+    for (const record of knowledge[collection] || []) {
+      for (const key of Object.keys(record)) {
+        if (known.has(key)) continue
+        warnings.push({
+          rule: 'unrecognised-field',
+          collection,
+          id: record.id,
+          message: `${collection} ${record.id}: unrecognised field "${key}" - kept, but check the spelling`
+        })
+      }
+    }
+  }
+
+  const legacyActionLinks = (knowledge.relationships || []).filter((r) => r.type === 'leads-to-action')
+  if (legacyActionLinks.length) {
+    warnings.push({
+      rule: 'legacy-relationship-type',
+      message:
+        `${legacyActionLinks.length} relationships still use leads-to-action (insight -> action). ` +
+        'Dependents point at what they rely on, so these should be responds-to-insight ' +
+        '(action -> insight) or traversal from a screen stops at the insight.'
+    })
+  }
+
+  const needsWithoutEvidence = (knowledge.needs || []).filter((need) => !(need.evidenceIds || []).length)
+  if (needsWithoutEvidence.length) {
+    infos.push({
+      rule: 'need-without-evidence',
+      count: needsWithoutEvidence.length,
+      ids: needsWithoutEvidence.map((need) => need.id),
+      message: `${needsWithoutEvidence.length} of ${knowledge.needs.length} needs cite no evidence`
+    })
+  }
+
+  const needLinked = new Set()
+  for (const relationship of knowledge.relationships || []) {
+    if (index.insights && index.insights[relationship.from] && index.needs && index.needs[relationship.to]) {
+      needLinked.add(relationship.from)
+    }
+  }
+  const unlinkedInsights = (knowledge.insights || []).filter((insight) => !needLinked.has(insight.id))
+  if (unlinkedInsights.length) {
+    infos.push({
+      rule: 'insight-without-need',
+      count: unlinkedInsights.length,
+      ids: unlinkedInsights.map((insight) => insight.id),
+      message:
+        `${unlinkedInsights.length} of ${knowledge.insights.length} insights link to no user need - ` +
+        'usually a gap in the needs layer rather than a bad insight'
+    })
+  }
+
+  const roundsWithInsights = new Set((knowledge.insights || []).map((insight) => insight.roundId))
+  const emptyRounds = (knowledge.researchRounds || []).filter((round) => !roundsWithInsights.has(round.id))
+  if (emptyRounds.length) {
+    infos.push({
+      rule: 'round-without-insights',
+      count: emptyRounds.length,
+      ids: emptyRounds.map((round) => round.id),
+      message: `${emptyRounds.length} of ${knowledge.researchRounds.length} research rounds produced no insights`
+    })
+  }
+
+  const screensWithoutNeeds = (knowledge.screens || []).filter((screen) => !(screen.needIds || []).length)
+  if (screensWithoutNeeds.length) {
+    infos.push({
+      rule: 'screen-without-need',
+      count: screensWithoutNeeds.length,
+      ids: screensWithoutNeeds.map((screen) => screen.id),
+      message: `${screensWithoutNeeds.length} of ${knowledge.screens.length} screens trace back to no user need`
+    })
+  }
+
+  const defaultPriority = (knowledge.needs || []).filter((need) => need.priority === 'medium')
+  if (defaultPriority.length && knowledge.needs.length) {
+    const share = Math.round((defaultPriority.length / knowledge.needs.length) * 100)
+    if (share >= 50) {
+      infos.push({
+        rule: 'priority-unset',
+        count: defaultPriority.length,
+        message:
+          `${defaultPriority.length} of ${knowledge.needs.length} needs (${share}%) sit at priority "medium" - ` +
+          'likely the import default rather than a decision, so priority cannot sequence design work yet'
+      })
+    }
+  }
+
+  return { warnings, infos }
+}
+
+module.exports = { lintKnowledge }