@try-works/dsh-memory 0.1.18 → 0.1.20

package/src/layers.js

@@ -1,178 +1,178 @@
-// Layered storage: semantic/episodic/procedural/learnings are INDEX files that point at
-// one file per topic inside a sibling directory. A single append-only file per layer grows
-// without bound and becomes hard to read, diff and search; one file per topic keeps every
-// file small and greppable, and the index is regenerated from the topic files so it can
-// never drift from them.
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
-import { layerDir } from './store.js'
-import { LAYER_DIRS, LAYERED, LAYER_FILES, layersForScope, parseEntries } from './entry.js'
-import { slugify } from './workspace-key.js'
-
-// Re-exported so callers can reach the layer vocabulary from either module.
-export { LAYER_DIRS, LAYERED }
-/** True when this layer stores its entries as per-topic files. */
-export function isLayered(layer) { return Object.hasOwn(LAYER_DIRS, layer) }
-
-/** Display title for a scope, matching the layer templates. */
-export function scopeTitle(scope, key) { return scope === 'global' ? 'Global' : (key ?? 'workspace') }
-
-export function layerTopicsDir(root, scope, key, layer) { return join(layerDir(root, scope, key), LAYER_DIRS[layer]) }
-export function layerIndexPath(root, scope, key, layer) { return join(layerDir(root, scope, key), LAYER_FILES[layer]) }
-
-/** Filesystem-safe slug for a topic heading; never empty. */
-export function topicSlug(topic) { return slugify(topic) || 'untitled' }
-
-/** The file one topic's entries live in. */
-export function topicFilePath(root, scope, key, layer, topic) {
-  return join(layerTopicsDir(root, scope, key, layer), topicSlug(topic) + '.md')
-}
-
-/** Heading of a topic file, so a generated file explains itself. */
-export function topicFileTitle(scope, key, layer, topic) {
-  return '# ' + scopeTitle(scope, key) + ' \u2014 ' + (LAYER_FILES[layer] ?? layer).replace(/\.md$/, '') + ': ' + topic
-}
-
-/**
- * Read every topic file of one layer.
- * @returns {{slug: string, file: string, text: string, entries: object[]}[]} sorted by slug.
- */
-export function readLayerTopics(root, scope, key, layer) {
-  const dir = layerTopicsDir(root, scope, key, layer)
-  if (!existsSync(dir)) return []
-  return readdirSync(dir)
-    .filter((name) => name.endsWith('.md'))
-    .sort()
-    .map((name) => {
-      const file = join(dir, name)
-      const text = readFileSync(file, 'utf8')
-      return { slug: name.replace(/\.md$/, ''), file, text, entries: parseEntries(text) }
-    })
-}
-
-/** Concatenated text of a layer, for id allocation across every topic file. */
-export function layerText(root, scope, key, layer) {
-  return readLayerTopics(root, scope, key, layer).map((topic) => topic.text).join('\n')
-}
-
-/** The relative link target from the layer index to a topic file. */
-function topicLink(layer, slug) { return LAYER_DIRS[layer] + '/' + slug + '.md' }
-
-/** Render a layer index: a topic map pointing at the per-topic files. */
-export function renderLayerIndex(scope, key, layer, topics) {
-  const title = '# ' + scopeTitle(scope, key) + ' \u2014 ' + (LAYER_FILES[layer] ?? layer).replace(/\.md$/, '')
-  const intro = 'Topic index. Entries live in one file per topic under ' + LAYER_DIRS[layer] + '/.'
-  if (topics.length === 0) return [title, '', intro, '', '(no topics yet)', ''].join('\n')
-  const rows = topics.map((topic) => {
-    // A history topic IS a day, so the day is the useful label; elsewhere the first
-    // entry heading names the topic better than its slug.
-    const heading = layer === 'history' ? topic.slug : (topic.entries[0] ? topic.entries[0].heading : topic.slug)
-    const count = topic.entries.length
-    const updated = topic.entries.reduce((latest, entry) => {
-      const stamp = entry.updated ?? entry.date ?? ''
-      return stamp > latest ? stamp : latest
-    }, '')
-    const when = updated ? ', updated ' + String(updated).slice(0, 10) : ''
-    return '- [' + heading + '](' + topicLink(layer, topic.slug) + ') \u2014 ' + count
-      + (count === 1 ? ' entry' : ' entries') + when
-  })
-  return [title, '', intro, '', ...rows, ''].join('\n')
-}
-
-/** Regenerate one layer's index from its topic files. */
-export function rebuildLayerIndex(root, scope, key, layer) {
-  if (!isLayered(layer)) return
-  const topics = readLayerTopics(root, scope, key, layer)
-  mkdirSync(layerDir(root, scope, key), { recursive: true })
-  writeFileSync(layerIndexPath(root, scope, key, layer), renderLayerIndex(scope, key, layer, topics), 'utf8')
-}
-
-/** Regenerate every layered index for one scope. */
-export function rebuildLayerIndexes(root, scope, key, layers) {
-  for (const layer of layers ?? layersForScope(scope)) rebuildLayerIndex(root, scope, key, layer)
-}
-
-/** Append an entry block to its topic file, creating the file (and dir) as needed. */
-export function appendToTopic(root, scope, key, layer, topic, block) {
-  mkdirSync(layerTopicsDir(root, scope, key, layer), { recursive: true })
-  const file = topicFilePath(root, scope, key, layer, topic)
-  if (!existsSync(file)) {
-    writeFileSync(file, topicFileTitle(scope, key, layer, topic) + '\n\n' + block + '\n', 'utf8')
-    return file
-  }
-  const existing = readFileSync(file, 'utf8')
-  const sep = existing.endsWith('\n') ? '' : '\n'
-  writeFileSync(file, existing + sep + block + '\n', 'utf8')
-  return file
-}
-
-/** The topic file holding an entry id, or undefined. Searches every layered kind of one scope. */
-export function findEntryFile(root, scope, key, id, layers) {
-  for (const layer of layers ?? layersForScope(scope)) {
-    for (const topic of readLayerTopics(root, scope, key, layer)) {
-      if (topic.entries.some((entry) => entry.id === id)) return topic.file
-    }
-  }
-  return undefined
-}
-
-/** Scope and workspace key from a root-relative ledger path. */
-export function scopeOfFile(rel) {
-  const parts = String(rel ?? '').split('/')
-  if (parts[0] === 'global') return { scope: 'global', key: undefined }
-  if (parts[0] === 'workspaces' && parts[1]) return { scope: 'workspace', key: parts[1] }
-  return undefined
-}
-
-/**
- * Move entries out of a pre-layering layer file into per-topic files and rebuild the index
- * from them. Idempotent: a layer whose index already holds only pointers moves nothing.
- * @returns how many entries were moved.
- */
-export function migrateLayer(root, scope, key, layer) {
-  const file = layerIndexPath(root, scope, key, layer)
-  if (!existsSync(file)) return 0
-  const text = readFileSync(file, 'utf8')
-  const entries = parseEntries(text)
-  if (entries.length === 0) return 0
-  const lines = text.split('\n')
-  let moved = 0
-  for (const entry of entries) {
-    const block = lines.slice(entry.startLine - 1, entry.endLine).join('\n').trimEnd()
-    if (block === '') continue
-    appendToTopic(root, scope, key, layer, entry.heading, block)
-    moved += 1
-  }
-  rebuildLayerIndex(root, scope, key, layer)
-  return moved
-}
-
-/**
- * Bring every scope onto layered storage: make sure each layered kind has its directory,
- * move any entries still sitting in a single layer file, and rebuild its index.
- * Runs on load and is idempotent.
- */
-export function migrateToLayered(root) {
-  const wdir = join(root, 'workspaces')
-  let keys = []
-  try { keys = readdirSync(wdir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name) } catch { keys = [] }
-  const scopes = [['global', undefined], ...keys.map((key) => ['workspace', key])]
-  let moved = 0
-  for (const [scope, key] of scopes) {
-    for (const layer of layersForScope(scope)) {
-      mkdirSync(layerTopicsDir(root, scope, key, layer), { recursive: true })
-      moved += migrateLayer(root, scope, key, layer)
-      // A scope that predates this layer still needs its index file. Rebuilding is safe
-      // here because migrateLayer has already lifted any entries out of it.
-      if (!existsSync(layerIndexPath(root, scope, key, layer))) rebuildLayerIndex(root, scope, key, layer)
-    }
-  }
-  return moved
-}
-
-/** Every topic file of one scope, for search and the ledger. */
-export function listTopicFiles(root, scope, key, layers) {
-  const out = []
-  for (const layer of layers ?? layersForScope(scope)) for (const topic of readLayerTopics(root, scope, key, layer)) out.push(topic.file)
-  return out
-}
+// Layered storage: semantic/episodic/procedural/learnings are INDEX files that point at
+// one file per topic inside a sibling directory. A single append-only file per layer grows
+// without bound and becomes hard to read, diff and search; one file per topic keeps every
+// file small and greppable, and the index is regenerated from the topic files so it can
+// never drift from them.
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { layerDir } from './store.js'
+import { LAYER_DIRS, LAYERED, LAYER_FILES, layersForScope, parseEntries } from './entry.js'
+import { slugify } from './workspace-key.js'
+
+// Re-exported so callers can reach the layer vocabulary from either module.
+export { LAYER_DIRS, LAYERED }
+/** True when this layer stores its entries as per-topic files. */
+export function isLayered(layer) { return Object.hasOwn(LAYER_DIRS, layer) }
+
+/** Display title for a scope, matching the layer templates. */
+export function scopeTitle(scope, key) { return scope === 'global' ? 'Global' : (key ?? 'workspace') }
+
+export function layerTopicsDir(root, scope, key, layer) { return join(layerDir(root, scope, key), LAYER_DIRS[layer]) }
+export function layerIndexPath(root, scope, key, layer) { return join(layerDir(root, scope, key), LAYER_FILES[layer]) }
+
+/** Filesystem-safe slug for a topic heading; never empty. */
+export function topicSlug(topic) { return slugify(topic) || 'untitled' }
+
+/** The file one topic's entries live in. */
+export function topicFilePath(root, scope, key, layer, topic) {
+  return join(layerTopicsDir(root, scope, key, layer), topicSlug(topic) + '.md')
+}
+
+/** Heading of a topic file, so a generated file explains itself. */
+export function topicFileTitle(scope, key, layer, topic) {
+  return '# ' + scopeTitle(scope, key) + ' \u2014 ' + (LAYER_FILES[layer] ?? layer).replace(/\.md$/, '') + ': ' + topic
+}
+
+/**
+ * Read every topic file of one layer.
+ * @returns {{slug: string, file: string, text: string, entries: object[]}[]} sorted by slug.
+ */
+export function readLayerTopics(root, scope, key, layer) {
+  const dir = layerTopicsDir(root, scope, key, layer)
+  if (!existsSync(dir)) return []
+  return readdirSync(dir)
+    .filter((name) => name.endsWith('.md'))
+    .sort()
+    .map((name) => {
+      const file = join(dir, name)
+      const text = readFileSync(file, 'utf8')
+      return { slug: name.replace(/\.md$/, ''), file, text, entries: parseEntries(text) }
+    })
+}
+
+/** Concatenated text of a layer, for id allocation across every topic file. */
+export function layerText(root, scope, key, layer) {
+  return readLayerTopics(root, scope, key, layer).map((topic) => topic.text).join('\n')
+}
+
+/** The relative link target from the layer index to a topic file. */
+function topicLink(layer, slug) { return LAYER_DIRS[layer] + '/' + slug + '.md' }
+
+/** Render a layer index: a topic map pointing at the per-topic files. */
+export function renderLayerIndex(scope, key, layer, topics) {
+  const title = '# ' + scopeTitle(scope, key) + ' \u2014 ' + (LAYER_FILES[layer] ?? layer).replace(/\.md$/, '')
+  const intro = 'Topic index. Entries live in one file per topic under ' + LAYER_DIRS[layer] + '/.'
+  if (topics.length === 0) return [title, '', intro, '', '(no topics yet)', ''].join('\n')
+  const rows = topics.map((topic) => {
+    // A history topic IS a day, so the day is the useful label; elsewhere the first
+    // entry heading names the topic better than its slug.
+    const heading = layer === 'history' ? topic.slug : (topic.entries[0] ? topic.entries[0].heading : topic.slug)
+    const count = topic.entries.length
+    const updated = topic.entries.reduce((latest, entry) => {
+      const stamp = entry.updated ?? entry.date ?? ''
+      return stamp > latest ? stamp : latest
+    }, '')
+    const when = updated ? ', updated ' + String(updated).slice(0, 10) : ''
+    return '- [' + heading + '](' + topicLink(layer, topic.slug) + ') \u2014 ' + count
+      + (count === 1 ? ' entry' : ' entries') + when
+  })
+  return [title, '', intro, '', ...rows, ''].join('\n')
+}
+
+/** Regenerate one layer's index from its topic files. */
+export function rebuildLayerIndex(root, scope, key, layer) {
+  if (!isLayered(layer)) return
+  const topics = readLayerTopics(root, scope, key, layer)
+  mkdirSync(layerDir(root, scope, key), { recursive: true })
+  writeFileSync(layerIndexPath(root, scope, key, layer), renderLayerIndex(scope, key, layer, topics), 'utf8')
+}
+
+/** Regenerate every layered index for one scope. */
+export function rebuildLayerIndexes(root, scope, key, layers) {
+  for (const layer of layers ?? layersForScope(scope)) rebuildLayerIndex(root, scope, key, layer)
+}
+
+/** Append an entry block to its topic file, creating the file (and dir) as needed. */
+export function appendToTopic(root, scope, key, layer, topic, block) {
+  mkdirSync(layerTopicsDir(root, scope, key, layer), { recursive: true })
+  const file = topicFilePath(root, scope, key, layer, topic)
+  if (!existsSync(file)) {
+    writeFileSync(file, topicFileTitle(scope, key, layer, topic) + '\n\n' + block + '\n', 'utf8')
+    return file
+  }
+  const existing = readFileSync(file, 'utf8')
+  const sep = existing.endsWith('\n') ? '' : '\n'
+  writeFileSync(file, existing + sep + block + '\n', 'utf8')
+  return file
+}
+
+/** The topic file holding an entry id, or undefined. Searches every layered kind of one scope. */
+export function findEntryFile(root, scope, key, id, layers) {
+  for (const layer of layers ?? layersForScope(scope)) {
+    for (const topic of readLayerTopics(root, scope, key, layer)) {
+      if (topic.entries.some((entry) => entry.id === id)) return topic.file
+    }
+  }
+  return undefined
+}
+
+/** Scope and workspace key from a root-relative ledger path. */
+export function scopeOfFile(rel) {
+  const parts = String(rel ?? '').split('/')
+  if (parts[0] === 'global') return { scope: 'global', key: undefined }
+  if (parts[0] === 'workspaces' && parts[1]) return { scope: 'workspace', key: parts[1] }
+  return undefined
+}
+
+/**
+ * Move entries out of a pre-layering layer file into per-topic files and rebuild the index
+ * from them. Idempotent: a layer whose index already holds only pointers moves nothing.
+ * @returns how many entries were moved.
+ */
+export function migrateLayer(root, scope, key, layer) {
+  const file = layerIndexPath(root, scope, key, layer)
+  if (!existsSync(file)) return 0
+  const text = readFileSync(file, 'utf8')
+  const entries = parseEntries(text)
+  if (entries.length === 0) return 0
+  const lines = text.split('\n')
+  let moved = 0
+  for (const entry of entries) {
+    const block = lines.slice(entry.startLine - 1, entry.endLine).join('\n').trimEnd()
+    if (block === '') continue
+    appendToTopic(root, scope, key, layer, entry.heading, block)
+    moved += 1
+  }
+  rebuildLayerIndex(root, scope, key, layer)
+  return moved
+}
+
+/**
+ * Bring every scope onto layered storage: make sure each layered kind has its directory,
+ * move any entries still sitting in a single layer file, and rebuild its index.
+ * Runs on load and is idempotent.
+ */
+export function migrateToLayered(root) {
+  const wdir = join(root, 'workspaces')
+  let keys = []
+  try { keys = readdirSync(wdir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name) } catch { keys = [] }
+  const scopes = [['global', undefined], ...keys.map((key) => ['workspace', key])]
+  let moved = 0
+  for (const [scope, key] of scopes) {
+    for (const layer of layersForScope(scope)) {
+      mkdirSync(layerTopicsDir(root, scope, key, layer), { recursive: true })
+      moved += migrateLayer(root, scope, key, layer)
+      // A scope that predates this layer still needs its index file. Rebuilding is safe
+      // here because migrateLayer has already lifted any entries out of it.
+      if (!existsSync(layerIndexPath(root, scope, key, layer))) rebuildLayerIndex(root, scope, key, layer)
+    }
+  }
+  return moved
+}
+
+/** Every topic file of one scope, for search and the ledger. */
+export function listTopicFiles(root, scope, key, layers) {
+  const out = []
+  for (const layer of layers ?? layersForScope(scope)) for (const topic of readLayerTopics(root, scope, key, layer)) out.push(topic.file)
+  return out
+}

package/src/ledger.js

@@ -1,19 +1,19 @@
-// Derived entry ledger: per-entry metadata (file, layer, line span, importance,
-// dates) rebuilt from the markdown in one step. Feeds ranking + freshness.
-import { readFileSync } from 'node:fs'
-import { relative } from 'node:path'
-import { indexedFiles, layerOfFile } from './files.js'
-import { parseEntries } from './entry.js'
-
-export function buildLedger(root) {
-  const entries = []
-  for (const file of indexedFiles(root)) {
-    const rel = relative(root, file).replace(/\\/g, '/')
-    const layer = layerOfFile(root, file)
-    if (!layer) continue
-    for (const e of parseEntries(readFileSync(file, 'utf8'))) {
-      entries.push({ ...e, file: rel, layer })
-    }
-  }
-  return entries
-}
+// Derived entry ledger: per-entry metadata (file, layer, line span, importance,
+// dates) rebuilt from the markdown in one step. Feeds ranking + freshness.
+import { readFileSync } from 'node:fs'
+import { relative } from 'node:path'
+import { indexedFiles, layerOfFile } from './files.js'
+import { parseEntries } from './entry.js'
+
+export function buildLedger(root) {
+  const entries = []
+  for (const file of indexedFiles(root)) {
+    const rel = relative(root, file).replace(/\\/g, '/')
+    const layer = layerOfFile(root, file)
+    if (!layer) continue
+    for (const e of parseEntries(readFileSync(file, 'utf8'))) {
+      entries.push({ ...e, file: rel, layer })
+    }
+  }
+  return entries
+}