k0-board 0.2.0 → 0.4.0

package/web/fuzzy.js

@@ -1,47 +1,99 @@
 // ── Searching the names ───────────────────────────────────────────────────────
 // It does not look for the exact word: it looks for the letters you typed, in the order you
-// typed them, scattered through the path. So `audrep` finds `docs/audit-report.md` and `bapl`
-// finds `docs/backlog/plans/`.
+// typed them, scattered through the file's **name**. So `audrep` finds `docs/audit-report.md`.
+//
+// The directory is never searched. It was, once: `.env` scattered its four letters across
+// `.planning/milestones/` and turned up `v1.0-ROADMAP.md`, a file that has nothing to do with
+// what was typed and gives no way to see why it is there — three of the four letters are in a
+// folder name nobody is looking at. A path is not a sentence you meant to write; a file name is.
 //
 // The score exists to put what you actually meant at the top. Worth more: a letter next to the
-// previous one, a letter at the start of a word, and anything in the file's name rather than in
-// the directory — because you usually reach a file through its name, not through where it is.
+// previous one, and a letter at the start of a word.
+
+const BOUNDARY = new Set(['-', '_', '.', ' '])
 
-const BOUNDARY = new Set(['/', '-', '_', '.', ' '])
+/** What is really searched for: the spaces mean nothing here, and neither does the case. */
+const wanted = (query) => String(query ?? '').trim().toLowerCase().replace(/\s+/g, '')
 
 /**
- * How much `text` looks like `query`: the higher, the more alike. `-1` when the letters simply
- * are not there. With an empty search it is 0 for everybody, and the caller decides the order.
+ * The one walk through the file's name, which produces both numbers this file exists for: how
+ * alike the two are, and **which letters** made it so.
+ *
+ * They come out of the same walk on purpose. Underlining letters that a second, separate pass had
+ * chosen would sooner or later underline something the ranking had not used — and a row that says
+ * "this is why I am here" has to be telling the truth.
+ *
+ * `at` comes back as positions inside the whole `text`, not just the name: the caller was handed
+ * a path, and a position only means something next to the path it was taken from.
+ *
+ * Returns `null` when the letters are not there at all.
  */
-export function score(text, query) {
-  const q = String(query ?? '').trim().toLowerCase().replace(/\s+/g, '')
-  if (!q) return 0
+function trace(text, q) {
   const s = String(text ?? '')
-  const low = s.toLowerCase()
-
-  // Where the file name starts: from there on every hit is worth more.
+  // Where the file name starts. Everything before this is the directory, and it is not searched.
   const nameAt = s.lastIndexOf('/') + 1
+  const name = s.slice(nameAt)
+  const low = name.toLowerCase()
 
+  const at = []
   let total = 0
-  let at = 0
+  let from = 0
   let last = -2
   for (const ch of q) {
-    const hit = low.indexOf(ch, at)
-    if (hit === -1) return -1
+    const hit = low.indexOf(ch, from)
+    if (hit === -1) return null
 
     let point = 1
     if (hit === last + 1) point += 4 // next to the previous one
-    if (hit === 0 || BOUNDARY.has(s[hit - 1])) point += 3 // the start of a word
-    else if (s[hit] >= 'A' && s[hit] <= 'Z') point += 2 // the start of a word in camelCase
-    if (hit >= nameAt) point += 2 // in the file name, not the directory
+    if (hit === 0 || BOUNDARY.has(name[hit - 1])) point += 3 // the start of a word
+    else if (name[hit] >= 'A' && name[hit] <= 'Z') point += 2 // the start of a word in camelCase
 
     total += point
+    at.push(hit + nameAt)
     last = hit
-    at = hit + 1
+    from = hit + 1
   }
 
   // On equal hits the shorter name wins: there is less around what you were looking for.
-  return total - s.length * 0.01
+  return { total: total - name.length * 0.01, at }
+}
+
+/**
+ * How much `text` looks like `query`: the higher, the more alike. `-1` when the letters simply
+ * are not there. With an empty search it is 0 for everybody, and the caller decides the order.
+ */
+export function score(text, query) {
+  const q = wanted(query)
+  if (!q) return 0
+  return trace(text, q)?.total ?? -1
+}
+
+/**
+ * Where in `text` the letters of `query` were found, in order — the positions the score was built
+ * from, so a row can underline them and show why it matched. `null` when there was no match, or
+ * nothing to search for.
+ */
+export function positions(text, query) {
+  const q = wanted(query)
+  if (!q) return null
+  return trace(text, q)?.at ?? null
+}
+
+/**
+ * The same positions gathered into stretches — `[[from, to], …]`, the end not included.
+ *
+ * Neighbouring letters belong together: `audrep` against `audit-report.md` found two pieces of
+ * two words, and that is what it should look like. Marked one letter at a time it looks like six
+ * separate coincidences, which is the opposite of what happened.
+ */
+export function runs(at) {
+  const out = []
+  for (const i of at ?? []) {
+    const last = out[out.length - 1]
+    if (last && last[1] === i) last[1] = i + 1
+    else out.push([i, i + 1])
+  }
+  return out
 }
 
 /** The rows that match, most alike first. `key` says where to look. */

package/web/json.js

@@ -0,0 +1,145 @@
+// ── A JSON file, laid out ─────────────────────────────────────────────────────
+// A `package.json` shown as text is a wall you read with your finger. What you actually want to
+// know is what is under `scripts`, and everything else can stay shut until you ask for it.
+//
+// So: a tree that folds. The folding is `<details>`, which the browser already knows how to do —
+// no state to keep, nothing to wire up, and it works before any script has run.
+//
+// And with the folding comes the reason this file also does the searching. The browser's own find
+// does not look inside a closed `<details>`: on a folded tree ⌘F says "not found" for something
+// that is right there. So the search is done here, on the data, and the branches that hold a
+// result are handed back already open.
+//
+// It knows nothing about the page: text in, a string of HTML out. That is what makes it testable.
+
+/**
+ * Written again rather than imported: this module is pulled in by the tests, which run in Node,
+ * where the browser's absolute `/md.js` does not resolve. Four lines are cheaper than making
+ * every pure module share a build.
+ */
+const esc = (s) =>
+  String(s ?? '').replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c])
+
+/** How deep it arrives open. Two levels is the shape of the file; three is already its contents. */
+const OPEN_DEPTH = 2
+
+/**
+ * Past this it is not a document any more, it is a dump — and the tree would be a megabyte of
+ * HTML that no browser lays out quickly. The page falls back to showing the text as it is.
+ */
+const MAX_NODES = 20000
+
+/**
+ * The word found inside a piece of text, wrapped so it can be seen, and how many times it is
+ * there. The count is what the page shows next to the box: without it a search that finds
+ * nothing looks exactly like a search that has not run.
+ */
+export function mark(value, query) {
+  const text = String(value ?? '')
+  if (!query) return { html: esc(text), n: 0 }
+  const hay = text.toLowerCase()
+  const needle = query.toLowerCase()
+  let out = ''
+  let at = 0
+  let n = 0
+  for (let i = hay.indexOf(needle, at); i !== -1; i = hay.indexOf(needle, at)) {
+    out += `${esc(text.slice(at, i))}<mark>${esc(text.slice(i, i + needle.length))}</mark>`
+    at = i + needle.length
+    n += 1
+  }
+  return { html: out + esc(text.slice(at)), n }
+}
+
+/** How a value is written, and what colour it is: the type is the colour. */
+function leafValue(value) {
+  if (value === null) return { text: 'null', cls: 'nil' }
+  if (typeof value === 'string') return { text: value, cls: 'str' }
+  if (typeof value === 'number') return { text: String(value), cls: 'num' }
+  if (typeof value === 'boolean') return { text: String(value), cls: 'bool' }
+  return { text: String(value), cls: 'str' }
+}
+
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`
+
+/**
+ * One entry of the tree, and everything under it.
+ *
+ * The number of results comes back up from the leaves rather than being counted again at the
+ * top, because it is the same walk: whoever found a result also knows which branch has to be
+ * open for it to be visible.
+ */
+function node(key, value, depth, query, budget) {
+  if (budget.left <= 0) return { html: '', n: 0 }
+  budget.left -= 1
+
+  const label = key === null ? null : mark(key, query)
+  const name = label ? `<b class="key">${label.html}</b>` : ''
+
+  if (value !== null && typeof value === 'object') {
+    const entries = Array.isArray(value)
+      ? value.map((v, i) => [String(i), v])
+      : Object.entries(value)
+    const brace = Array.isArray(value) ? ['[', ']'] : ['{', '}']
+    const size = Array.isArray(value)
+      ? plural(entries.length, 'item', 'items')
+      : plural(entries.length, 'key', 'keys')
+
+    // An empty object has nothing to open: a summary with no contents is a fold that lies.
+    if (!entries.length) {
+      return {
+        html: `<div class="leaf">${name}<span class="v empty">${brace[0]}${brace[1]}</span></div>`,
+        n: label?.n ?? 0,
+      }
+    }
+
+    let inner = ''
+    let n = label?.n ?? 0
+    for (const [k, v] of entries) {
+      const child = node(k, v, depth + 1, query, budget)
+      inner += child.html
+      n += child.n
+    }
+    // With something searched for, only the branches holding a result open — that is the whole
+    // point of doing the search here. With nothing searched for, the first levels open, which is
+    // the shape of the file without its contents.
+    const open = query ? n > 0 : depth < OPEN_DEPTH
+    return {
+      html:
+        `<details class="node"${open ? ' open' : ''}><summary>${name}` +
+        `<span class="brace">${brace[0]}${brace[1]}</span><em>${size}</em></summary>` +
+        `<div class="kids">${inner}</div></details>`,
+      n,
+    }
+  }
+
+  const { text, cls } = leafValue(value)
+  const hit = mark(text, query)
+  return {
+    html: `<div class="leaf">${name}<span class="v ${cls}">${hit.html}</span></div>`,
+    n: (label?.n ?? 0) + hit.n,
+  }
+}
+
+/**
+ * The whole file as a tree, with `query` picked out inside it.
+ *
+ * When it does not parse, nothing is invented: the reason comes back and the page shows the text
+ * exactly as it is on disk, which is the only honest thing to show for a file that is broken —
+ * and usually the reason you opened it.
+ *
+ * Returns `{ html, matches, error }`.
+ */
+export function tree(text, query = '') {
+  let data
+  try {
+    data = JSON.parse(text)
+  } catch (e) {
+    return { html: '', matches: 0, error: String(e.message || e) }
+  }
+  const budget = { left: MAX_NODES }
+  const out = node(null, data, 0, String(query || '').trim(), budget)
+  if (budget.left <= 0) {
+    return { html: '', matches: 0, error: 'This file is too big to lay out as a tree.' }
+  }
+  return { html: `<div class="json">${out.html}</div>`, matches: out.n, error: null }
+}