@mnstry/atelier 0.2.0-alpha.6 → 0.2.0-alpha.8

package/src/projection/obsidian/materialize/byte-lens.mjs

@@ -0,0 +1,98 @@
+import { createHash } from 'node:crypto'
+import { ObsidianContractRefusal } from '../contracts.mjs'
+
+// Raw byte lens: where the front matter and the body of one Markdown source
+// sit, as byte offsets into the Buffer exactly as read. Nothing is decoded into
+// a working string, no newline is normalized and no byte is dropped. A source
+// the lens cannot delimit with certainty refuses; it is never guessed at.
+
+const UTF8_BOM = Buffer.from([0xef, 0xbb, 0xbf])
+const LF = 0x0a
+const CR = 0x0d
+const DASH = 0x2d
+const SPACE = 0x20
+const TAB = 0x09
+
+export function refuse(code, message, detail = {}) {
+  throw new ObsidianContractRefusal(code, message, detail)
+}
+
+export function sha256Digest(bytes) {
+  return `sha256:${createHash('sha256').update(bytes).digest('hex')}`
+}
+
+export function assertStrictUtf8(buffer, detail = {}) {
+  if (!Buffer.isBuffer(buffer)) refuse('invalid-source', 'a source must be read as a Buffer', detail)
+  try {
+    new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(buffer)
+  } catch {
+    refuse('malformed-utf8', 'source is not valid UTF-8; it is not emitted', detail)
+  }
+}
+
+// One line starting at `offset`: [contentEnd, nextOffset, eol]. `eol` is
+// 'lf', 'crlf' or 'none' (end of buffer).
+function lineAt(buffer, offset) {
+  const newline = buffer.indexOf(LF, offset)
+  if (newline === -1) return { contentEnd: buffer.length, next: buffer.length, eol: 'none' }
+  const crlf = newline > offset && buffer[newline - 1] === CR
+  return { contentEnd: crlf ? newline - 1 : newline, next: newline + 1, eol: crlf ? 'crlf' : 'lf' }
+}
+
+function isDelimiterLine(buffer, start, contentEnd) {
+  if (contentEnd - start < 3) return null
+  for (let index = start; index < start + 3; index += 1) if (buffer[index] !== DASH) return null
+  let trailing = 0
+  for (let index = start + 3; index < contentEnd; index += 1) {
+    if (buffer[index] !== SPACE && buffer[index] !== TAB) return null
+    trailing += 1
+  }
+  return { trailing }
+}
+
+function finalNewlineState(buffer) {
+  if (buffer.length === 0 || buffer[buffer.length - 1] !== LF) return 'none'
+  return buffer.length > 1 && buffer[buffer.length - 2] === CR ? 'crlf' : 'lf'
+}
+
+// Returns { bom, frontmatter, body, finalNewline } with half-open byte ranges.
+// `bom` and `frontmatter` are null when absent.
+export function readMarkdownLens(buffer, detail = {}) {
+  assertStrictUtf8(buffer, detail)
+  const hasBom = buffer.length >= 3 && buffer.subarray(0, 3).equals(UTF8_BOM)
+  const start = hasBom ? 3 : 0
+  const bom = hasBom ? { start: 0, end: 3 } : null
+  const whole = { bom, frontmatter: null, body: { start, end: buffer.length }, finalNewline: finalNewlineState(buffer) }
+
+  // A bare carriage return after the opening dashes is a line ending to some
+  // readers and ordinary text to others.
+  if (buffer.subarray(start, start + 3).equals(Buffer.from('---')) && buffer[start + 3] === CR && buffer[start + 4] !== LF) {
+    refuse('ambiguous-frontmatter', 'the opening front matter delimiter ends in a bare carriage return', detail)
+  }
+  const first = lineAt(buffer, start)
+  const opening = isDelimiterLine(buffer, start, first.contentEnd)
+  if (!opening) return whole
+  // The canonical graph reads a delimiter only as the exact first bytes of the
+  // text. Any opening it would read differently from an editor is ambiguous.
+  if (hasBom) refuse('ambiguous-frontmatter', 'a byte order prefix precedes a front matter delimiter', detail)
+  if (opening.trailing > 0) refuse('ambiguous-frontmatter', 'the opening front matter delimiter carries trailing whitespace', detail)
+  if (first.eol === 'none') refuse('ambiguous-frontmatter', 'the source is a lone front matter delimiter', detail)
+
+  let offset = first.next
+  let lines = 0
+  while (offset < buffer.length) {
+    const line = lineAt(buffer, offset)
+    if (isDelimiterLine(buffer, offset, line.contentEnd)) {
+      if (lines === 0) refuse('ambiguous-frontmatter', 'front matter closes immediately after it opens', detail)
+      if (line.eol === 'none') refuse('ambiguous-frontmatter', 'the closing front matter delimiter has no line ending', detail)
+      const region = buffer.subarray(start, line.next)
+      for (let index = 0; index < region.length; index += 1) {
+        if (region[index] === CR && region[index + 1] !== LF) refuse('ambiguous-frontmatter', 'front matter uses a bare carriage return as a line ending', detail)
+      }
+      return { ...whole, frontmatter: { start, end: line.next }, body: { start: line.next, end: buffer.length } }
+    }
+    lines += 1
+    offset = line.next
+  }
+  return refuse('ambiguous-frontmatter', 'front matter opens and never closes', detail)
+}

package/src/projection/obsidian/materialize/index.mjs

@@ -0,0 +1,7 @@
+// Materialization: the pure preparation layer for an Obsidian view. Nothing
+// here writes into a vault; publication is a separate protocol.
+export { EMITTER_VERSION, createPreparationCache, prepareView, withEligibility } from './prepare-view.mjs'
+export { readMarkdownLens, assertStrictUtf8, sha256Digest } from './byte-lens.mjs'
+export { PATH_REGISTRY_SCHEMA, allocateWorkspacePaths, collisionKey, emptyPathRegistry } from './path-registry.mjs'
+export { POLICY_DISABLED_CORE_PLUGINS, POLICY_SETTINGS_PATH, SETTINGS_ROOT, isPolicySettingsPath, isUserOwnedSettingsPath, prepareSettings } from './settings.mjs'
+export { stagePreparedView } from './stage.mjs'

package/src/projection/obsidian/materialize/path-registry.mjs

@@ -0,0 +1,105 @@
+import { identitySuffix, notePath } from '../contracts.mjs'
+import { refuse } from './byte-lens.mjs'
+
+// The persistent path registry: one readable note path per canonical identity,
+// allocated once per workspace and reused by every scope and generation. A
+// path, once allocated, never changes because a source title changed.
+//
+// The registry is workspace-wide, not view-wide: preparing any view allocates
+// for every visible node of the workspace and returns the whole grown registry
+// to the caller, which holds it as machine-private trusted state. It therefore
+// names visible nodes outside the view's selection. It never includes a
+// withheld node: allocation runs over the visible nodes only. A view's
+// manifest and notes carry only the paths of the notes the view holds.
+
+export const PATH_REGISTRY_SCHEMA = 'atelier-obsidian-path-registry/v1'
+
+const NOTE_PATH = /^notes\/([^/\\\u0000]+)--([0-9a-f]{12,64})\.md$/
+const MAX_COMPONENT_BYTES = 255
+const MAX_SUFFIX = 64
+// Bytes left for the readable title once the longest suffix, the separator and
+// the extension are reserved, so lengthening a suffix never overflows a name.
+const TITLE_BYTE_BUDGET = MAX_COMPONENT_BYTES - '--'.length - MAX_SUFFIX - '.md'.length
+export const DEFAULT_MAX_FULL_PATH_BYTES = 1024
+
+const compare = (left, right) => (left < right ? -1 : left > right ? 1 : 0)
+export const identityKey = (repoId, nodeId) => `${repoId}\u0000${nodeId}`
+
+// Two paths that a case-insensitive or normalization-insensitive filesystem
+// would treat as one share a collision key.
+export function collisionKey(value) {
+  return value.normalize('NFKC').toUpperCase().toLowerCase().normalize('NFKC')
+}
+
+export function titleWithinBudget(title, budget = TITLE_BYTE_BUDGET) {
+  let kept = ''
+  let bytes = 0
+  for (const character of String(title ?? '').normalize('NFC')) {
+    bytes += Buffer.byteLength(character, 'utf8')
+    if (bytes > budget) break
+    kept += character
+  }
+  return kept
+}
+
+export function emptyPathRegistry(workspaceId) {
+  return { schema: PATH_REGISTRY_SCHEMA, workspaceId, entries: [] }
+}
+
+function indexRegistry(registry, workspaceId) {
+  if (registry === undefined || registry === null) return { byIdentity: new Map(), taken: new Map() }
+  if (registry.schema !== PATH_REGISTRY_SCHEMA || !Array.isArray(registry.entries)) refuse('invalid-path-registry', 'path registry has an unknown shape')
+  if (registry.workspaceId !== workspaceId) refuse('invalid-path-registry', 'path registry belongs to another workspace')
+  const byIdentity = new Map()
+  const taken = new Map()
+  for (const entry of registry.entries) {
+    const match = typeof entry?.path === 'string' ? entry.path.match(NOTE_PATH) : null
+    if (!match || typeof entry.repoId !== 'string' || typeof entry.nodeId !== 'string') refuse('invalid-path-registry', 'path registry entry is malformed')
+    if (identitySuffix(entry.repoId, entry.nodeId, 64).slice(0, match[2].length) !== match[2]) {
+      refuse('invalid-path-registry', 'path registry entry carries a suffix that is not derived from its identity')
+    }
+    const key = identityKey(entry.repoId, entry.nodeId)
+    if (byIdentity.has(key)) refuse('duplicate-identity', 'path registry repeats a canonical identity')
+    if (taken.has(collisionKey(entry.path))) refuse('path-collision', 'path registry allocates one path to more than one identity')
+    byIdentity.set(key, entry.path)
+    taken.set(collisionKey(entry.path), key)
+  }
+  return { byIdentity, taken }
+}
+
+// Allocates a path for every node that lacks one and returns the grown
+// registry. `nodes` are canonical nodes ({ repo, id, title }); allocation order
+// is canonical-identity order, so the result depends on the inputs alone.
+export function allocateWorkspacePaths({ registry, workspaceId, nodes, vaultRootBytes = 0, maxFullPathBytes = DEFAULT_MAX_FULL_PATH_BYTES }) {
+  const { byIdentity, taken } = indexRegistry(registry, workspaceId)
+  const seen = new Set()
+  const ordered = [...nodes].sort((left, right) => compare(left.repo, right.repo) || compare(left.id, right.id))
+  for (const node of ordered) {
+    const key = identityKey(node.repo, node.id)
+    if (seen.has(key)) refuse('duplicate-identity', 'more than one node carries the same canonical identity')
+    seen.add(key)
+    if (byIdentity.has(key)) continue
+    const titled = { repo: node.repo, id: node.id, title: titleWithinBudget(node.title) }
+    let length = 12
+    let candidate = notePath(titled, length)
+    while (taken.has(collisionKey(candidate))) {
+      length += 4
+      if (length > MAX_SUFFIX) refuse('path-collision', 'unable to allocate a distinct note path')
+      candidate = notePath(titled, length)
+    }
+    byIdentity.set(key, candidate)
+    taken.set(collisionKey(candidate), key)
+  }
+  for (const candidate of byIdentity.values()) {
+    const name = candidate.slice('notes/'.length)
+    if (Buffer.byteLength(name, 'utf8') > MAX_COMPONENT_BYTES || vaultRootBytes + 1 + Buffer.byteLength(candidate, 'utf8') > maxFullPathBytes) {
+      refuse('path-too-long', 'an allocated note path exceeds the supported path length')
+    }
+  }
+  const entries = [...byIdentity].map(([key, allocated]) => {
+    const [repoId, nodeId] = key.split('\u0000')
+    return { repoId, nodeId, path: allocated }
+  })
+  entries.sort((left, right) => compare(left.repoId, right.repoId) || compare(left.nodeId, right.nodeId))
+  return { registry: { schema: PATH_REGISTRY_SCHEMA, workspaceId, entries }, pathOf: (repoId, nodeId) => byIdentity.get(identityKey(repoId, nodeId)) ?? null }
+}