@carlesandres/house 0.4.14 → 0.5.0

package/src/discovery/walk.ts

@@ -1,209 +0,0 @@
-import { readdir, readFile } from "node:fs/promises"
-import { extname, join, relative, resolve } from "node:path"
-import { Data, Effect, Stream } from "effect"
-import ignore, { type Ignore } from "ignore"
-import type { ShowCategory } from "./show.ts"
-
-export interface FileEntry {
-	/** Absolute path on disk. */
-	readonly path: string
-	/** Path relative to the discovery root, with forward slashes. */
-	readonly relativePath: string
-	/** File basename. */
-	readonly name: string
-}
-
-export interface DiscoveryWarning {
-	readonly path: string
-	readonly cause: unknown
-}
-
-export interface WalkOptions {
-	/** Categories of normally-skipped entries to opt into. Empty (the
-	 *  default) yields the conservative set: no dotfiles, no gitignored
-	 *  entries. Order is irrelevant — semantics are set membership. Hard
-	 *  skips (`node_modules`, `.git`, `.venv`) always apply. */
-	readonly show?: Iterable<ShowCategory>
-	/** Additional file extensions to include alongside `.md` / `.markdown`.
-	 *  Values may include or omit the leading dot. */
-	readonly extensions?: Iterable<string>
-	/** 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")<{
-	readonly root: string
-	readonly cause: unknown
-}> {}
-
-const BASE_EXTENSIONS = new Set([".md", ".markdown"])
-const HARD_SKIP_DIRS = new Set(["node_modules", ".git", ".venv"])
-
-const normalizeExtension = (ext: string): string => {
-	const trimmed = ext.trim().toLowerCase()
-	return trimmed.startsWith(".") ? trimmed : `.${trimmed}`
-}
-
-interface IgnoreLevel {
-	readonly dir: string
-	readonly ig: Ignore
-}
-
-const isIgnored = (
-	entryPath: string,
-	isDirectory: boolean,
-	levels: readonly IgnoreLevel[],
-): boolean => {
-	for (const { dir, ig } of levels) {
-		const rel = relative(dir, entryPath)
-		if (!rel || rel.startsWith("..")) continue
-		const candidate = isDirectory ? `${rel}/` : rel
-		if (ig.ignores(candidate)) return true
-	}
-	return false
-}
-
-const tryLoadGitignore = async (dir: string): Promise<Ignore | null> => {
-	try {
-		const content = await readFile(join(dir, ".gitignore"), "utf8")
-		return ignore().add(content)
-	} catch {
-		return null
-	}
-}
-
-const sortEntries = <T extends { name: string; isDirectory: () => boolean }>(
-	entries: readonly T[],
-): T[] =>
-	[...entries].sort((a, b) => {
-		const aDir = a.isDirectory()
-		const bDir = b.isDirectory()
-		if (aDir !== bDir) {
-			return aDir ? 1 : -1
-		}
-		return a.name.localeCompare(b.name)
-	})
-
-/**
- * DFS generator. Yields each markdown FileEntry as it is discovered, before
- * descending further. Per-directory sort still happens before yielding so
- * 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`
- * on a slow filesystem still runs to completion before we notice — the
- * generator only exits at the next checkpoint.
- */
-async function* walkDirGen(
-	dirPath: string,
-	rootPath: string,
-	parentLevels: readonly IgnoreLevel[],
-	opts: { showHidden: boolean; showGitignored: boolean; extensions: ReadonlySet<string> },
-	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) {
-		const ig = await tryLoadGitignore(dirPath)
-		if (signal.aborted) return
-		if (ig) levels = [...parentLevels, { dir: dirPath, ig }]
-	}
-
-	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)) {
-		if (signal.aborted) return
-
-		// Never follow symlinks — cycle hazard, and a markdown reader doesn't
-		// need them. May be relaxed (files only) in a later iteration.
-		if (entry.isSymbolicLink()) continue
-
-		const entryPath = join(dirPath, entry.name)
-
-		if (entry.isDirectory()) {
-			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, onWarning, signal)
-			continue
-		}
-
-		if (!entry.isFile()) continue
-		if (!opts.showHidden && entry.name.startsWith(".")) continue
-		const allowed = opts.extensions
-		if (!allowed.has(extname(entry.name).toLowerCase())) continue
-		if (!opts.showGitignored && isIgnored(entryPath, false, levels)) continue
-
-		yield {
-			path: entryPath,
-			relativePath: relative(rootPath, entryPath),
-			name: entry.name,
-		}
-	}
-}
-
-/**
- * Stream markdown files under `root`. Entries arrive in DFS order respecting
- * the per-directory sort. The stream is interruptible at syscall boundaries:
- * the consumer's teardown trips an AbortController, and the generator exits
- * at its next `signal.aborted` check.
- *
- * Rules (see DESIGN.md §6):
- * - Extensions: `.md`, `.markdown`, plus configured extras.
- * - Hard skips (always): `node_modules`, `.git`, `.venv`.
- * - Hidden files/dirs (leading `.`) skipped unless `show` contains `"hidden"`.
- * - `.gitignore` honored, including nested `.gitignore` files.
- * - Symlinks not followed.
- * - Sort: files before directories, alphabetical within each group.
- */
-export const walk = (
-	root: string,
-	options: WalkOptions = {},
-): Stream.Stream<FileEntry, DiscoveryError> => {
-	const absRoot = resolve(root)
-	const show = new Set<ShowCategory>(options.show ?? [])
-	const extensions = new Set(BASE_EXTENSIONS)
-	for (const ext of options.extensions ?? []) extensions.add(normalizeExtension(ext))
-	const opts = {
-		showHidden: show.has("hidden"),
-		showGitignored: show.has("gitignored"),
-		extensions,
-	}
-	const onWarning = options.onWarning ?? null
-	const controller = new AbortController()
-	const iterable: AsyncIterable<FileEntry> = {
-		[Symbol.asyncIterator]() {
-			const gen = walkDirGen(absRoot, absRoot, [], opts, onWarning, controller.signal)
-			return {
-				next: () => gen.next(),
-				return: async (value?: void) => {
-					controller.abort()
-					return gen.return(value as void)
-				},
-			}
-		},
-	}
-	return Stream.fromAsyncIterable(iterable, (cause) => new DiscoveryError({ root, cause }))
-}
-
-/**
- * Test/convenience helper: collect the full walk into an array. Mirrors the
- * pre-streaming `walk()` signature so call sites that don't need streaming
- * (notably tests) stay terse.
- */
-export const walkToArray = (
-	root: string,
-	options: WalkOptions = {},
-): Effect.Effect<readonly FileEntry[], DiscoveryError> =>
-	Stream.runCollect(walk(root, options)).pipe(Effect.map((chunk) => Array.from(chunk)))

package/src/index.tsx

@@ -1,469 +0,0 @@
-#!/usr/bin/env bun
-/** house — entry point. Boots the browser TUI or `--serve` preview. */
-
-import { stat } from "node:fs/promises"
-import { homedir } from "node:os"
-import { dirname, isAbsolute, relative, resolve } from "node:path"
-import { createCliRenderer } from "@opentui/core"
-import { createRoot } from "@opentui/react"
-import { RegistryProvider } from "@effect/atom-react"
-import { Cause, Duration, Effect, Fiber, Stream } from "effect"
-import { useEffect, useRef, useState } from "react"
-import pkg from "../package.json" with { type: "json" }
-import { Browser, type StartupFocus } from "./Browser.tsx"
-import { parseArgv, usage } from "./cli/argv.ts"
-import { defaultConfigPath, formatConfigError, loadConfig } from "./config/load.ts"
-import { parseShowList, SHOW_CATEGORIES, type ShowCategory } from "./discovery/show.ts"
-import { formatDiscoveryRootLabel } from "./discovery/rootLabel.ts"
-import { walk, type FileEntry } from "./discovery/walk.ts"
-import { openInBrowser } from "./serve/openBrowser.ts"
-import { startServer } from "./serve/server.ts"
-import { setActiveTheme } from "./theme/colors.ts"
-import { themeAtom, type ThemeState } from "./theme/atom.ts"
-import { getThemeDefinition } from "./theme/registry.ts"
-import { formatQuitNotice } from "./update/notice.ts"
-import { currentUpdateInfo, startUpdateProbe } from "./update/runtime.ts"
-import { useUpdateNotice } from "./update/useUpdateNotice.ts"
-
-/**
- * DiscoverShell — owns the streaming walk for the Browser. Mounts Browser
- * immediately with `files=[]` and pushes entries as the stream emits.
- *
- * Batching: `Stream.groupedWithin(64, 60ms)` coalesces bursts so we don't
- * trigger one React render per file. Tuned by feel — small enough that
- * results still feel live on tiny trees, large enough to keep render
- * frequency sane on big ones. Revisit if profiling says otherwise.
- *
- * Cancellation: the walk runs on a forked fiber; unmount interrupts it.
- * `Quit` in Browser tears down the renderer and exits, which propagates
- * naturally — the cleanup effect still fires before process.exit completes.
- */
-const pathIsDirectory = async (path: string): Promise<boolean> => {
-	try {
-		return (await stat(path)).isDirectory()
-	} catch {
-		return false
-	}
-}
-
-const findGitRoot = async (cwd: string): Promise<string> => {
-	const start = resolve(cwd)
-	let current = start
-	for (;;) {
-		if (await pathIsDirectory(resolve(current, ".git"))) return current
-		const parent = dirname(current)
-		if (parent === current) return start
-		current = parent
-	}
-}
-
-export const resolveDiscoveryRoot = async ({
-	cliRoot,
-	defaultRoot,
-	cwd,
-}: {
-	readonly cliRoot: string | null
-	readonly defaultRoot: "cwd" | "git"
-	readonly cwd: string
-}): Promise<string> => {
-	if (cliRoot !== null) return resolve(cwd, cliRoot)
-	if (defaultRoot === "git") return findGitRoot(cwd)
-	return cwd
-}
-
-export const validateDiscoveryRoot = async (root: string): Promise<void> => {
-	let stats: Awaited<ReturnType<typeof stat>>
-	try {
-		stats = await stat(root)
-	} catch (err) {
-		throw new Error(`cannot access discovery root ${root}: ${String(err)}`)
-	}
-	if (!stats.isDirectory()) {
-		throw new Error(`discovery root must be a directory, got file ${root}`)
-	}
-}
-
-export const formatPartialDiscoveryStatus = ({
-	skippedCount,
-	lastSkippedPath,
-}: {
-	readonly skippedCount: number
-	readonly lastSkippedPath: string | null
-}): string | null => {
-	if (skippedCount <= 0) return null
-	const noun = skippedCount === 1 ? "directory" : "directories"
-	const suffix = lastSkippedPath && skippedCount === 1 ? `: ${lastSkippedPath}` : ""
-	return `scan incomplete: skipped ${skippedCount} ${noun}${suffix}`
-}
-
-export const formatFatalDiscoveryStatus = (): string => "scan failed: unable to read discovery root"
-
-interface DiscoverShellProps {
-	readonly target: string
-	readonly initialQuery: string
-	/** Resolved discovery vocabulary from the config layer. The shift+a
-	 *  toggle (#145) is session-only sugar that flips between this set
-	 *  and the full vocabulary; the underlying categories remain
-	 *  independent everywhere else. */
-	readonly initialShow: readonly ShowCategory[]
-	readonly rootLabel?: string
-	readonly extensions: readonly string[]
-	readonly wrapWidth: number
-	readonly initialWrap: boolean
-	readonly startupFocus: StartupFocus
-}
-
-export const DiscoverShell = ({
-	target,
-	initialQuery,
-	initialShow,
-	rootLabel = target,
-	extensions,
-	wrapWidth,
-	initialWrap,
-	startupFocus,
-}: DiscoverShellProps) => {
-	const updateNotice = useUpdateNotice()
-	const [show, setShow] = useState<readonly ShowCategory[]>(initialShow)
-	const [files, setFiles] = useState<readonly FileEntry[]>([])
-	const [scanning, setScanning] = useState<boolean>(true)
-	const [scanError, setScanError] = useState<string | null>(null)
-	const [skippedDirCount, setSkippedDirCount] = useState<number>(0)
-	const [lastSkippedDir, setLastSkippedDir] = useState<string | null>(null)
-	// Files arrive in a ref-tracked count so the status string can show
-	// "indexing… N" even when React hasn't yet flushed the latest setFiles.
-	const countRef = useRef(0)
-
-	useEffect(() => {
-		// Restart from a clean slate every time the discovery set changes.
-		// Required for the `all` toggle (#145): without this, a flip would
-		// concatenate the new walk onto stale entries and leave `scanning`
-		// stuck on whatever the previous walk last set it to.
-		setFiles([])
-		setScanning(true)
-		setScanError(null)
-		setSkippedDirCount(0)
-		setLastSkippedDir(null)
-		countRef.current = 0
-		const warnedProgram = walk(target, {
-			show,
-			extensions,
-			onWarning: ({ path }) => {
-				const relativePath = relative(resolve(target), path)
-				setSkippedDirCount((prev) => prev + 1)
-				setLastSkippedDir(
-					relativePath.length > 0 && !relativePath.startsWith("..") && !isAbsolute(relativePath)
-						? relativePath
-						: path,
-				)
-			},
-		}).pipe(
-			Stream.groupedWithin(64, Duration.millis(60)),
-			Stream.runForEach((chunk) =>
-				Effect.sync(() => {
-					const arr = Array.from(chunk)
-					if (arr.length === 0) return
-					countRef.current += arr.length
-					setFiles((prev) => [...prev, ...arr])
-				}),
-			),
-			Effect.matchCauseEffect({
-				onSuccess: () => Effect.sync(() => setScanning(false)),
-				onFailure: (cause) =>
-					Effect.sync(() => {
-						if (Cause.hasInterrupts(cause)) return
-						setScanError(formatFatalDiscoveryStatus())
-						setScanning(false)
-					}),
-			}),
-		)
-		const fiber = Effect.runFork(warnedProgram)
-		return () => {
-			Effect.runFork(Fiber.interrupt(fiber))
-		}
-	}, [target, show, extensions])
-
-	const discoveryStatus =
-		scanError ??
-		(scanning
-			? `indexing… ${countRef.current}`
-			: formatPartialDiscoveryStatus({
-					skippedCount: skippedDirCount,
-					lastSkippedPath: lastSkippedDir,
-				}))
-
-	return (
-		<Browser
-			files={files}
-			initialQuery={initialQuery}
-			wrapWidth={wrapWidth}
-			initialWrap={initialWrap}
-			rootLabel={rootLabel}
-			discoveryStatus={discoveryStatus}
-			startupFocus={startupFocus}
-			updateNotice={updateNotice}
-			onToggleAll={() => {
-				// shift+a is the only place the categories are treated as a
-				// single thing. If every category is already on, fall back
-				// to "show none"; otherwise opt into the full vocabulary.
-				// Each press is a stable round-trip between [] and full.
-				const next: readonly ShowCategory[] =
-					show.length === SHOW_CATEGORIES.length ? [] : [...SHOW_CATEGORIES]
-				setShow(next)
-			}}
-		/>
-	)
-}
-
-export const resolveInitialQuery = ({
-	pathArg,
-	discoveryRoot,
-	cwd,
-}: {
-	readonly pathArg: string | null
-	readonly discoveryRoot: string
-	readonly cwd: string
-}): string => {
-	if (pathArg === null) return ""
-	const resolvedPath = resolve(cwd, pathArg)
-	const rel = relative(discoveryRoot, resolvedPath)
-	if (rel.length === 0) return ""
-	if (!rel.startsWith("..") && !isAbsolute(rel)) return rel
-	if (pathArg.startsWith("./")) return pathArg.slice(2)
-	return pathArg
-}
-
-let updateExitHookRegistered = false
-
-if (import.meta.main) {
-	const args = parseArgv(Bun.argv.slice(2))
-
-	if (args.help) {
-		console.log(usage)
-		process.exit(0)
-	}
-	if (args.wrapConflict) {
-		console.error("house: --wrap and --no-wrap cannot be used together")
-		process.exit(2)
-	}
-	if (Bun.argv.slice(2).includes("--width") && args.width === null) {
-		console.error("house: --width requires a positive integer")
-		process.exit(2)
-	}
-	if (args.version) {
-		console.log(pkg.version)
-		process.exit(0)
-	}
-	if (args.configPath) {
-		console.log(defaultConfigPath())
-		process.exit(0)
-	}
-
-	// Parse --show eagerly so an invalid token fails fast with the CLI-style
-	// "house: ..." message, before any I/O work in loadConfig kicks off.
-	let cliShow: readonly ShowCategory[] | null = null
-	if (args.show !== null) {
-		const parsed = parseShowList(args.show)
-		if (!parsed.ok) {
-			console.error(
-				`house: --show: unknown category "${parsed.invalid.join('", "')}" (valid: ${SHOW_CATEGORIES.join(", ")})`,
-			)
-			process.exit(2)
-		}
-		cliShow = parsed.value
-	}
-
-	const config = await Effect.runPromise(
-		loadConfig({
-			cli: {
-				theme: args.theme,
-				tone: args.tone,
-				extensions:
-					args.extensions === null
-						? null
-						: args.extensions
-								.split(",")
-								.map((s) => s.trim())
-								.filter(Boolean),
-				// `--show` replaces env/file when present (set semantics —
-				// no per-category merge across sources). `null` falls through.
-				show: cliShow,
-				focus:
-					args.focus === "sidebar" || args.focus === "reader" || args.focus === "filter"
-						? args.focus
-						: null,
-				width:
-					args.width === null
-						? null
-						: (() => {
-								const n = Number.parseInt(args.width, 10)
-								if (!/^\d+$/.test(args.width) || !Number.isSafeInteger(n) || n <= 0) {
-									console.error(`house: --width must be a positive integer, got "${args.width}"`)
-									process.exit(2)
-								}
-								return n
-							})(),
-				wrap: args.wrap,
-			},
-		}),
-	).catch((err: unknown) => {
-		console.error(`house: ${formatConfigError(err)}`)
-		process.exit(2)
-	})
-	const {
-		theme: themeId,
-		tone,
-		extensions,
-		show,
-		focus: startupFocus,
-		defaultRoot,
-		width: wrapWidth,
-		wrap: initialWrap,
-	} = config
-	const themeDef = getThemeDefinition(themeId)
-	if (themeDef === undefined) {
-		// Unreachable: Config.schema validated themeId against themeDefinitions.
-		console.error(`house: unknown theme "${themeId}"`)
-		process.exit(2)
-	}
-	setActiveTheme(themeDef, tone)
-
-	const cwd = process.cwd()
-	const discoveryRoot = await resolveDiscoveryRoot({ cliRoot: args.root, defaultRoot, cwd })
-	const initialQuery = resolveInitialQuery({ pathArg: args.path, discoveryRoot, cwd })
-
-	if (args.serve) {
-		const target = args.path
-		if (target === null) {
-			console.error("house: --serve requires a file path")
-			process.exit(2)
-		}
-		let stats: Awaited<ReturnType<typeof stat>>
-		try {
-			stats = await stat(target)
-		} catch (err) {
-			console.error(`house: cannot access ${target}: ${String(err)}`)
-			process.exit(1)
-		}
-		if (stats.isDirectory()) {
-			console.error(`house: --serve requires a file, got directory ${target}`)
-			process.exit(2)
-		}
-		let port = 0
-		if (args.port !== null) {
-			const n = Number.parseInt(args.port, 10)
-			if (!Number.isFinite(n) || n < 0 || n > 65535) {
-				console.error(`house: --port must be 0-65535, got "${args.port}"`)
-				process.exit(2)
-			}
-			port = n
-		}
-		const handle = startServer({ path: target, port })
-		console.log(`house serving ${target} at ${handle.url}`)
-		console.log("press ctrl+c to stop")
-		openInBrowser(handle.url)
-		const shutdown = async () => {
-			await handle.stop()
-			process.exit(0)
-		}
-		process.on("SIGINT", shutdown)
-		process.on("SIGTERM", shutdown)
-		// Bun.serve keeps the event loop alive until stop().
-	} else {
-		if (args.focus !== null) {
-			if (args.focus !== "sidebar" && args.focus !== "reader" && args.focus !== "filter") {
-				console.error(
-					`house: --focus must be "sidebar", "reader", or "filter", got "${args.focus}"`,
-				)
-				process.exit(2)
-			}
-		}
-		await runTui({
-			discoveryRoot,
-			initialQuery,
-			themeId,
-			tone,
-			wrapWidth,
-			initialWrap,
-			show,
-			extensions,
-			startupFocus,
-			updateCheck: !args.noUpdateCheck,
-		})
-	}
-}
-
-interface TuiBootOptions {
-	readonly discoveryRoot: string
-	readonly initialQuery: string
-	readonly themeId: string
-	readonly tone: "dark" | "light"
-	readonly wrapWidth: number
-	readonly initialWrap: boolean
-	readonly show: readonly ShowCategory[]
-	readonly extensions: readonly string[]
-	readonly startupFocus: StartupFocus
-	/** Run the npm-registry probe and surface the "update available" notice.
-	 *  False suppresses both the toast and the quit-time print. */
-	readonly updateCheck: boolean
-}
-
-async function runTui({
-	discoveryRoot,
-	initialQuery,
-	themeId,
-	tone,
-	wrapWidth,
-	initialWrap,
-	show,
-	extensions,
-	startupFocus,
-	updateCheck,
-}: TuiBootOptions): Promise<void> {
-	if (updateCheck) {
-		// Fire the npm-registry probe in the background. Result lands in a
-		// module singleton; the React tree picks it up via `useUpdateNotice`
-		// for the footer toast, and the 'exit' hook below reads it
-		// synchronously for the scrollback print. Failures are silent — this
-		// whole feature is opportunistic.
-		startUpdateProbe(pkg.name, pkg.version)
-		// Register once per process. Multiple 'exit' listeners would print
-		// the notice multiple times if runTui were ever re-entered.
-		if (!updateExitHookRegistered) {
-			updateExitHookRegistered = true
-			process.on("exit", () => {
-				const info = currentUpdateInfo()
-				if (info) process.stderr.write(formatQuitNotice(info))
-			})
-		}
-	}
-
-	const renderer = await createCliRenderer({
-		exitOnCtrlC: false,
-		useMouse: true,
-		enableMouseMovement: true,
-		screenMode: "alternate-screen",
-	})
-	renderer.useMouse = true
-	const initialTheme: ThemeState = { id: themeId, tone }
-	try {
-		await validateDiscoveryRoot(discoveryRoot)
-	} catch (err) {
-		console.error(`house: ${err instanceof Error ? err.message : String(err)}`)
-		process.exit(1)
-	}
-	createRoot(renderer).render(
-		<RegistryProvider initialValues={[[themeAtom, initialTheme]]}>
-			<DiscoverShell
-				target={discoveryRoot}
-				initialQuery={initialQuery}
-				initialShow={show}
-				rootLabel={formatDiscoveryRootLabel({ discoveryRoot, home: homedir() })}
-				extensions={extensions}
-				wrapWidth={wrapWidth}
-				initialWrap={initialWrap}
-				startupFocus={startupFocus}
-			/>
-		</RegistryProvider>,
-	)
-}