@carlesandres/house 0.4.7 → 0.4.9

package/src/commands/buildCommands.ts

@@ -2,9 +2,8 @@
  * Derive palette commands from `browserBindings` plus the annotation map.
  *
  * The annotation map is the *only* hand-written list keyed by binding id:
- * it carries (a) hide flags for bindings that are pure keystroke nav, and
- * (b) title rewrites for bindings whose `description` reads as a help-row
- * entry rather than a palette command. Every other binding is exposed
+ * it carries title rewrites and metadata for bindings whose raw
+ * `description` reads awkwardly as a palette command. Every enabled binding is exposed
  * verbatim — its `description` becomes the palette `title`, its first key
  * becomes the `shortcut`.
  *
@@ -30,49 +29,40 @@ interface Annotation {
 }
 
 /**
- * Pure-keystroke nav (j/k/space/b/[/]…) is intentionally hidden — those
- * bindings have no command-shaped meaning. Reader prev/next file (`[`/`]`)
- * and sidebar `open` (Return/l) are the borderline cases from #70 Q6a;
- * hidden in v1, reconsider if users ask. Title rewrites convert
- * help-overlay phrasing ("Toggle sidebar visibility") into imperative
- * palette phrasing ("Toggle sidebar"). See #70 design log §6.
+ * Title rewrites convert keymap phrasing into imperative palette phrasing.
+ * With the help overlay removed (#139), the palette is the only in-app full
+ * action index, so all currently-enabled actions stay discoverable here.
  */
 const annotations: Record<string, Annotation> = {
 	// --- Keep, with title rewrites where the binding description reads awkwardly as a command ---
 	quit: { category: "App" },
 	"focus.toggle": { title: "Toggle focus", category: "View" },
 	"sidebar.toggle": { title: "Toggle sidebar", category: "View" },
-	"help.toggle": { title: "Show help", category: "App" },
+	"sidebar.down": { category: "Navigation" },
+	"sidebar.up": { category: "Navigation" },
+	"sidebar.jumpDown": { category: "Navigation" },
+	"sidebar.jumpUp": { category: "Navigation" },
+	"sidebar.pageDown": { category: "Navigation" },
+	"sidebar.pageUp": { category: "Navigation" },
+	"sidebar.top": { category: "Navigation" },
+	"sidebar.bottom": { category: "Navigation" },
+	"sidebar.open": { title: "Open file", category: "Navigation" },
 	"filter.open": { title: "Filter files…", category: "Navigation" },
+	"filter.clearOrOpen": { category: "Navigation" },
 	"discovery.toggleAll": {
 		title: "Toggle hidden / gitignored files",
 		category: "Navigation",
 		keywords: ["hidden", "gitignore", "dotfiles", "all"],
 	},
+	"reader.back": { title: "Back to sidebar", category: "Navigation" },
+	"reader.prevFile": { title: "Previous file", category: "Navigation" },
+	"reader.nextFile": { title: "Next file", category: "Navigation" },
 	"serve.current": { title: "Open in browser", category: "File" },
 	"file.edit": { title: "Open in editor", category: "File", keywords: ["editor", "vim", "vscode"] },
 	"theme.next": { category: "Appearance" },
 	"theme.prev": { category: "Appearance" },
 	"theme.toneToggle": { title: "Toggle dark/light tone", category: "Appearance" },
 
-	// --- Hide: pure keystroke navigation (j/k/space/b/g/G…) ---
-	"sidebar.down": { hidden: true },
-	"sidebar.up": { hidden: true },
-	"sidebar.jumpDown": { hidden: true },
-	"sidebar.jumpUp": { hidden: true },
-	"sidebar.pageDown": { hidden: true },
-	"sidebar.pageUp": { hidden: true },
-	"sidebar.top": { hidden: true },
-	"sidebar.bottom": { hidden: true },
-
-	// --- Hide: borderline reader nav. `[`/`]` and Return-to-open feel command-shaped
-	//     but are pure keystroke navigation under the hood. #70 Q6a — reconsider
-	//     if user feedback expects them in the palette.
-	"sidebar.open": { hidden: true },
-	"reader.back": { hidden: true },
-	"reader.prevFile": { hidden: true },
-	"reader.nextFile": { hidden: true },
-
 	// --- Hide: the palette opener itself shouldn't appear in the palette ---
 	"palette.open": { hidden: true },
 }
@@ -80,8 +70,8 @@ const annotations: Record<string, Annotation> = {
 /**
  * Build the AppCommand list for a given render. Iterates `browserBindings`
  * in array order (the empty-query palette renders in this order, by design
- * — see #70 design log §empty-state ordering), drops hidden entries and
- * those whose `when` predicate currently returns false, and resolves
+ * — see #70 design log §empty-state ordering), drops explicitly-hidden entries
+ * and those whose `when` predicate currently returns false, and resolves
  * annotations to populate title / category / keywords.
  */
 export const buildCommands = (ctx: BrowserCtx): readonly AppCommand[] => {
@@ -89,9 +79,8 @@ export const buildCommands = (ctx: BrowserCtx): readonly AppCommand[] => {
 	for (const binding of browserBindings) {
 		const ann = annotations[binding.id]
 		if (ann?.hidden) continue
-		// Same gating the keymap dispatcher uses. Disabled bindings get
-		// hidden from the palette (per #70 Q5b — see #96 for the show-with-
-		// reason follow-up after the atom-driven migration).
+		// Same gating the keymap dispatcher uses. Disabled bindings stay out of
+		// the palette; #96 tracks a future show-with-reason mode.
 		if (binding.when && !binding.when(ctx)) continue
 		const cmd: AppCommand = {
 			id: binding.id,

package/src/commands/score.ts

@@ -34,7 +34,7 @@ const fuzzyIncludes = (text: string, query: string): boolean => {
 
 const searchText = (command: AppCommand): string =>
 	normalize(
-		[command.title, command.category, command.shortcut, ...(command.keywords ?? [])]
+		[command.title, command.category, ...(command.keywords ?? [])]
 			.filter((s): s is string => Boolean(s))
 			.join(" "),
 	)

package/src/discovery/filter.ts

@@ -3,12 +3,26 @@
  *
  * Matching stays intentionally small and pure: case-insensitive subsequence on
  * the filename and full relative path. Ranking prefers what users usually mean
- * in a sidebar:
- *   - filename matches above folder-only matches
- *   - files in the current folder above equally good nested matches
- *   - shallower paths above deeper ones as a soft tie-break
+ * in a sidebar (no configuration, no user knobs):
+ *   - filename matches above folder-only matches (zf/fzf-inspired strong bias)
+ *   - shallower / current-folder paths win over deep nested ones
+ *   - incidental matches purely from deep directory names are heavily demoted
+ *     so "nested folders bubbling up" does not happen for typical queries
  *
  * Empty query preserves discovery/tree order.
+ *
+ * The low-level fuzzyScore uses a "best alignment" scan (try every possible
+ * start position for the first query char, complete greedily, take the highest
+ * scoring match). This avoids the "early spurious char traps" a pure left-to-right
+ * greedy can hit on paths (e.g. "src/r.../readme" for query "readme" must prefer
+ * the boundary "r" in the filename, not the "r" in "src"). This draws from fzf's
+ * v1 "find occurrence then look for better" idea and the general principle that
+ * boundary+consecutive bonuses should win when they exist later in the string.
+ * We deliberately do not depend on fuzzysort/fuse/fzf here: the ranking *policy*
+ * (heavy filename bias, exact/stem bonuses, depth soft penalty) is application
+ * specific to "what makes a sidebar nice" and must be owned so end users get the
+ * good experience with zero configuration or thought. See DESIGN.md §7.4 and the
+ * filter tests.
  */
 
 import type { FileEntry } from "./walk.ts"
@@ -17,19 +31,41 @@ export const fuzzyScore = (query: string, target: string): number | null => {
 	if (query.length === 0) return 0
 	const q = query.toLowerCase()
 	const t = target.toLowerCase()
-	let qi = 0
-	let score = 0
-	let lastMatch = -2
-	for (let i = 0; i < t.length && qi < q.length; i++) {
-		if (t[i] !== q[qi]) continue
-		const isWordStart = i === 0 || t[i - 1] === "/"
-		score += isWordStart ? 10 : 1
-		if (lastMatch === i - 1) score += 5
-		lastMatch = i
-		qi++
+	if (q.length > t.length) return null
+
+	let best: number | null = null
+
+	// Best-alignment: try every viable start for q[0], then complete the rest
+	// greedily from there. Take the alignment that accumulates the most bonus
+	// points (word-start after /, consecutives). This is what gives good OOB
+	// results on tree paths without the caller doing extra work.
+	for (let start = 0; start < t.length; start++) {
+		if (t[start] !== q[0]) continue
+
+		let qi = 1
+		let score = 0
+		let lastMatch = start
+
+		// score first char
+		const isWordStart0 = start === 0 || t[start - 1] === "/"
+		score += isWordStart0 ? 10 : 1
+
+		let i = start + 1
+		for (; i < t.length && qi < q.length; i++) {
+			if (t[i] !== q[qi]) continue
+			const isWordStart = i === 0 || t[i - 1] === "/"
+			score += isWordStart ? 10 : 1
+			if (lastMatch === i - 1) score += 5
+			lastMatch = i
+			qi++
+		}
+
+		if (qi === q.length) {
+			if (best === null || score > best) best = score
+		}
 	}
-	if (qi < q.length) return null
-	return score
+
+	return best
 }
 
 const splitPath = (relativePath: string): { fileName: string; depth: number } => {
@@ -55,15 +91,31 @@ const rankFile = (query: string, file: FileEntry): number | null => {
 	const stem = fileStem(fileName).toLowerCase()
 	const nameScore = fuzzyScore(query, fileName) ?? 0
 
-	let score = pathScore * 10
-	score += nameScore * 100
+	let score = pathScore * 4
+	score += nameScore * 150
 
+	// Filename (and stem) priority — the heart of good sidebar UX.
+	// Users almost always mean "the file whose name contains this", not
+	// "some directory component that happens to have these letters".
 	if (name === q || stem === q) score += 5_000
 	else if (name.startsWith(q) || stem.startsWith(q)) score += 2_000
 	else if (name.includes(q)) score += 1_000
 
-	if (depth === 0) score += 300
-	score -= depth * 10
+	// Strong depth bias so less-nested files appear near the top.
+	// We want shallow files to win over deep "nested folders" even when
+	// the deep file has a decent path match (common with short queries or
+	// dir names). The penalty is now large enough to matter vs. the
+	// match bonuses. Root gets a big kick. This is the main lever for
+	// "position in the tree structure" without any user config.
+	if (depth === 0) score += 800
+	score -= depth * 120
+
+	// Extra penalty when the match is weak or absent in the *basename*.
+	// This aggressively demotes results where the hit is only because the
+	// file lives under a matching deep directory ("nested folders bubbling up").
+	if (nameScore == null || nameScore < 8) {
+		score -= depth * 80
+	}
 
 	return score
 }
@@ -73,16 +125,24 @@ const rankFile = (query: string, file: FileEntry): number | null => {
  * unchanged (preserves the discovery sort order). Non-empty query keeps
  * matches only, sorted by score desc; ties fall back to the input order so
  * the discovery sort still leaks through.
+ *
+ * All the "make this feel right for users exploring a tree" logic lives here
+ * (and in rankFile) so callers (Browser) and end users never have to think
+ * about or configure ranking.
  */
 export const filterFiles = (files: readonly FileEntry[], query: string): readonly FileEntry[] => {
 	if (query.length === 0) return files
-	const scored: { file: FileEntry; score: number; index: number }[] = []
+	const scored: { file: FileEntry; score: number; depth: number; index: number }[] = []
 	for (let i = 0; i < files.length; i++) {
 		const file = files[i]!
 		const score = rankFile(query, file)
 		if (score === null) continue
-		scored.push({ file, score, index: i })
+		const depth = (file.relativePath.match(/\//g) || []).length
+		scored.push({ file, score, depth, index: i })
 	}
-	scored.sort((a, b) => b.score - a.score || a.index - b.index)
+	// Primary: match quality (fuzzy + name bonuses - depth penalties already in score)
+	// Secondary: shallower depth wins (less nested near top)
+	// Tertiary: stable original discovery order
+	scored.sort((a, b) => b.score - a.score || a.depth - b.depth || a.index - b.index)
 	return scored.map((s) => s.file)
 }

package/src/discovery/walk.ts

@@ -13,7 +13,10 @@ export interface FileEntry {
 	readonly name: string
 }
 
-export type SortOrder = "dirs-first" | "files-first"
+export interface DiscoveryWarning {
+	readonly path: string
+	readonly cause: unknown
+}
 
 export interface WalkOptions {
 	/** Categories of normally-skipped entries to opt into. Empty (the
@@ -21,10 +24,10 @@ export interface WalkOptions {
 	 *  entries. Order is irrelevant — semantics are set membership. Hard
 	 *  skips (`node_modules`, `.git`, `.venv`) always apply. */
 	readonly show?: Iterable<ShowCategory>
-	/** Group order within each directory. Default `dirs-first`. */
-	readonly sort?: SortOrder
 	/** Include `.mdx` files alongside `.md`/`.markdown`. Default `true`. */
 	readonly mdx?: boolean
+	/** Non-fatal subtree read errors. Root-level failures still error the walk. */
+	readonly onWarning?: ((warning: DiscoveryWarning) => void) | null
 }
 
 export class DiscoveryError extends Data.TaggedError("DiscoveryError")<{
@@ -66,14 +69,12 @@ const tryLoadGitignore = async (dir: string): Promise<Ignore | null> => {
 
 const sortEntries = <T extends { name: string; isDirectory: () => boolean }>(
 	entries: readonly T[],
-	order: SortOrder,
 ): T[] =>
 	[...entries].sort((a, b) => {
 		const aDir = a.isDirectory()
 		const bDir = b.isDirectory()
 		if (aDir !== bDir) {
-			if (order === "files-first") return aDir ? 1 : -1
-			return aDir ? -1 : 1
+			return aDir ? 1 : -1
 		}
 		return a.name.localeCompare(b.name)
 	})
@@ -81,7 +82,7 @@ const sortEntries = <T extends { name: string; isDirectory: () => boolean }>(
 /**
  * DFS generator. Yields each markdown FileEntry as it is discovered, before
  * descending further. Per-directory sort still happens before yielding so
- * arrival order within a directory matches the configured sort.
+ * arrival order is files-first and alphabetical within each group.
  *
  * Cancellation: `signal.aborted` is checked between syscalls. Node's
  * `readdir` doesn't accept an AbortSignal, so a single in-flight `readdir`
@@ -92,10 +93,12 @@ async function* walkDirGen(
 	dirPath: string,
 	rootPath: string,
 	parentLevels: readonly IgnoreLevel[],
-	opts: { showHidden: boolean; showGitignored: boolean; sort: SortOrder; mdx: boolean },
+	opts: { showHidden: boolean; showGitignored: boolean; mdx: boolean },
+	onWarning: ((warning: DiscoveryWarning) => void) | null,
 	signal: AbortSignal,
 ): AsyncGenerator<FileEntry, void, void> {
 	if (signal.aborted) return
+	const isRoot = dirPath === rootPath
 
 	let levels = parentLevels
 	if (!opts.showGitignored) {
@@ -104,10 +107,17 @@ async function* walkDirGen(
 		if (ig) levels = [...parentLevels, { dir: dirPath, ig }]
 	}
 
-	const raw = await readdir(dirPath, { withFileTypes: true })
+	let raw
+	try {
+		raw = await readdir(dirPath, { withFileTypes: true })
+	} catch (error) {
+		if (isRoot) throw error
+		onWarning?.({ path: dirPath, cause: error })
+		return
+	}
 	if (signal.aborted) return
 
-	for (const entry of sortEntries(raw, opts.sort)) {
+	for (const entry of sortEntries(raw)) {
 		if (signal.aborted) return
 
 		// Never follow symlinks — cycle hazard, and a markdown reader doesn't
@@ -120,7 +130,7 @@ async function* walkDirGen(
 			if (HARD_SKIP_DIRS.has(entry.name)) continue
 			if (!opts.showHidden && entry.name.startsWith(".")) continue
 			if (!opts.showGitignored && isIgnored(entryPath, true, levels)) continue
-			yield* walkDirGen(entryPath, rootPath, levels, opts, signal)
+			yield* walkDirGen(entryPath, rootPath, levels, opts, onWarning, signal)
 			continue
 		}
 
@@ -150,8 +160,7 @@ async function* walkDirGen(
  * - Hidden files/dirs (leading `.`) skipped unless `show` contains `"hidden"`.
  * - `.gitignore` honored, including nested `.gitignore` files.
  * - Symlinks not followed.
- * - Sort: alphabetical within each group; directories before files
- *   (`dirs-first`, default) or files before directories (`files-first`).
+ * - Sort: files before directories, alphabetical within each group.
  */
 export const walk = (
 	root: string,
@@ -162,13 +171,13 @@ export const walk = (
 	const opts = {
 		showHidden: show.has("hidden"),
 		showGitignored: show.has("gitignored"),
-		sort: options.sort ?? ("dirs-first" as SortOrder),
 		mdx: options.mdx ?? true,
 	}
+	const onWarning = options.onWarning ?? null
 	const controller = new AbortController()
 	const iterable: AsyncIterable<FileEntry> = {
 		[Symbol.asyncIterator]() {
-			const gen = walkDirGen(absRoot, absRoot, [], opts, controller.signal)
+			const gen = walkDirGen(absRoot, absRoot, [], opts, onWarning, controller.signal)
 			return {
 				next: () => gen.next(),
 				return: async (value?: void) => {