bridges-cli 0.0.1

package/src/__tests__/Game.test.tsx

@@ -0,0 +1,198 @@
+import { setTimeout } from 'node:timers/promises'
+import { render } from 'ink-testing-library'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import Game from '../Game.tsx'
+
+const TEST_PUZZLE = { encoding: '3x3:1a1.c.2a2' }
+const TEST_PUZZLE_2 = { encoding: '3x3:3a3.c.1a1' }
+
+describe('Game', () => {
+    beforeEach(() => {
+        Object.defineProperty(process.stdin, 'isTTY', {
+            get: () => true,
+            configurable: true,
+        })
+        vi.spyOn(process.stdin, 'isTTY', 'get').mockReturnValue(true)
+    })
+
+    describe('--stdout flag', () => {
+        it('does not show instructions when stdout is true', () => {
+            const { lastFrame } = render(
+                <Game puzzles={[TEST_PUZZLE]} hasCustomPuzzle={false} stdout={true} />
+            )
+            expect(lastFrame()).not.toContain('Controls:')
+        })
+
+        it('shows instructions when stdout is false', () => {
+            const { lastFrame } = render(
+                <Game puzzles={[TEST_PUZZLE]} hasCustomPuzzle={false} stdout={false} />
+            )
+            expect(lastFrame()).toContain('Controls:')
+        })
+    })
+
+    describe('game controls', () => {
+        it('navigates to next puzzle with n key when interactive', async () => {
+            const { stdin, lastFrame } = render(
+                <Game
+                    puzzles={[TEST_PUZZLE, TEST_PUZZLE_2]}
+                    hasCustomPuzzle={false}
+                    stdout={false}
+                />
+            )
+
+            expect(lastFrame()).toEqual(`Bridges: Puzzle #1
+
+┌─────────────────┐
+│ ╭───╮     ╭───╮ │
+│ │ 1 │     │ 1 │ │
+│ ╰───╯     ╰───╯ │
+│                 │
+│                 │
+│                 │
+│ ╭───╮     ╭───╮ │
+│ │ 2 │     │ 2 │ │
+│ ╰───╯     ╰───╯ │
+└─────────────────┘
+
+Controls:
+p: Previous puzzle
+n: Next puzzle
+s: Show solution
+q: Quit`)
+
+            stdin.write('n')
+            await setTimeout(5)
+            expect(lastFrame()).toEqual(`Bridges: Puzzle #2
+
+┌─────────────────┐
+│ ╭───╮     ╭───╮ │
+│ │ 3 │     │ 3 │ │
+│ ╰───╯     ╰───╯ │
+│                 │
+│                 │
+│                 │
+│ ╭───╮     ╭───╮ │
+│ │ 1 │     │ 1 │ │
+│ ╰───╯     ╰───╯ │
+└─────────────────┘
+
+Controls:
+p: Previous puzzle
+n: Next puzzle
+s: Show solution
+q: Quit`)
+        })
+
+        it('navigates to previous puzzle with p key when interactive', async () => {
+            const { stdin, lastFrame } = render(
+                <Game
+                    puzzles={[TEST_PUZZLE, TEST_PUZZLE_2]}
+                    hasCustomPuzzle={false}
+                    stdout={false}
+                />
+            )
+
+            stdin.write('n')
+            await setTimeout(5)
+            expect(lastFrame()).toEqual(`Bridges: Puzzle #2
+
+┌─────────────────┐
+│ ╭───╮     ╭───╮ │
+│ │ 3 │     │ 3 │ │
+│ ╰───╯     ╰───╯ │
+│                 │
+│                 │
+│                 │
+│ ╭───╮     ╭───╮ │
+│ │ 1 │     │ 1 │ │
+│ ╰───╯     ╰───╯ │
+└─────────────────┘
+
+Controls:
+p: Previous puzzle
+n: Next puzzle
+s: Show solution
+q: Quit`)
+
+            stdin.write('p')
+            await setTimeout(5)
+            expect(lastFrame()).toEqual(`Bridges: Puzzle #1
+
+┌─────────────────┐
+│ ╭───╮     ╭───╮ │
+│ │ 1 │     │ 1 │ │
+│ ╰───╯     ╰───╯ │
+│                 │
+│                 │
+│                 │
+│ ╭───╮     ╭───╮ │
+│ │ 2 │     │ 2 │ │
+│ ╰───╯     ╰───╯ │
+└─────────────────┘
+
+Controls:
+p: Previous puzzle
+n: Next puzzle
+s: Show solution
+q: Quit`)
+        })
+
+        it('does not navigate past last puzzle', async () => {
+            const { stdin, lastFrame } = render(
+                <Game puzzles={[TEST_PUZZLE]} hasCustomPuzzle={false} stdout={false} />
+            )
+
+            stdin.write('n')
+            await setTimeout(5)
+            expect(lastFrame()).toEqual(`Bridges: Puzzle #1
+
+┌─────────────────┐
+│ ╭───╮     ╭───╮ │
+│ │ 1 │     │ 1 │ │
+│ ╰───╯     ╰───╯ │
+│                 │
+│                 │
+│                 │
+│ ╭───╮     ╭───╮ │
+│ │ 2 │     │ 2 │ │
+│ ╰───╯     ╰───╯ │
+└─────────────────┘
+
+Controls:
+p: Previous puzzle
+n: Next puzzle
+s: Show solution
+q: Quit`)
+        })
+
+        it('does not navigate before first puzzle', async () => {
+            const { stdin, lastFrame } = render(
+                <Game puzzles={[TEST_PUZZLE]} hasCustomPuzzle={false} stdout={false} />
+            )
+
+            stdin.write('p')
+            await setTimeout(5)
+            expect(lastFrame()).toEqual(`Bridges: Puzzle #1
+
+┌─────────────────┐
+│ ╭───╮     ╭───╮ │
+│ │ 1 │     │ 1 │ │
+│ ╰───╯     ╰───╯ │
+│                 │
+│                 │
+│                 │
+│ ╭───╮     ╭───╮ │
+│ │ 2 │     │ 2 │ │
+│ ╰───╯     ╰───╯ │
+└─────────────────┘
+
+Controls:
+p: Previous puzzle
+n: Next puzzle
+s: Show solution
+q: Quit`)
+        })
+    })
+})

package/src/components/HashiGrid.tsx

@@ -0,0 +1,110 @@
+import { Box } from 'ink'
+
+import type { HashiNodeData } from '../types.ts'
+import HashiRow from './HashiRow.tsx'
+import Header from './Header.tsx'
+import Messages from './Messages.tsx'
+
+export const ROW_HEIGHT = 3
+export const NODE_WIDTH = 5
+export const SPACE_BETWEEN = 0
+export const OUTER_PADDING = 1
+
+type HashiGridProps = {
+    /** The full data structure needed to render the grid. Height of the grid is determined
+     * by the number of rows here. */
+    rows: HashiNodeData[][]
+    /** Number of nodes in a row. */
+    numNodes: number
+    /** Show quit instructions */
+    showInstructions?: boolean
+    /** Current puzzle index for display */
+    puzzleIndex?: number
+    /** Current puzzle string for display */
+    puzzle?: string
+    /** Whether this is a custom puzzle */
+    isCustomPuzzle?: boolean
+    /** Whether this puzzle has a solution available */
+    hasSolution?: boolean
+    /** Whether to show the solution */
+    showSolution?: boolean
+}
+
+/**
+ * Ensure the grid data is consistent with a valid Hashiwokakero puzzle.
+ */
+export function validateGrid({ rows, numNodes }: HashiGridProps): void {
+    if (!rows || rows.length === 0) {
+        throw new Error('HashiGrid: empty data supplied')
+    }
+
+    let rowCount = 0
+    for (const nodes of rows) {
+        const prefix = `HashiGrid row ${rowCount}: `
+
+        if (nodes.length !== numNodes) {
+            throw new Error(`${prefix}expected ${numNodes} nodes, got ${nodes.length}`)
+        }
+
+        for (let i = 0; i < nodes.length; i++) {
+            const node = nodes[i]
+            if (!node) {
+                throw new Error(`${prefix}node at position ${i} is undefined`)
+            }
+            if (
+                typeof node.value !== 'number' &&
+                node.value !== '-' &&
+                node.value !== '=' &&
+                node.value !== ' ' &&
+                node.value !== '#' &&
+                node.value !== '|'
+            ) {
+                throw new Error(`${prefix}node at position ${i} has invalid value: ${node.value}`)
+            }
+        }
+        rowCount++
+    }
+}
+
+export default function HashiGrid({
+    rows,
+    numNodes,
+    showInstructions = false,
+    puzzleIndex = 0,
+    puzzle = '',
+    isCustomPuzzle = false,
+    hasSolution = false,
+    showSolution = false,
+}: HashiGridProps) {
+    validateGrid({ rows, numNodes })
+
+    const height = rows.length * ROW_HEIGHT + 2
+    const borderWidth = 2
+    const outerPadding = 2 * OUTER_PADDING
+    const innerPadding = (numNodes - 1) * SPACE_BETWEEN
+    const nodesWidth = numNodes * NODE_WIDTH
+    const width = borderWidth + outerPadding + innerPadding + nodesWidth
+
+    return (
+        <Box flexDirection="column">
+            <Header
+                puzzleIndex={puzzleIndex}
+                puzzle={puzzle}
+                isCustomPuzzle={isCustomPuzzle}
+                showSolution={showSolution}
+            />
+            <Box
+                borderStyle="single"
+                borderColor="white"
+                width={width}
+                height={height}
+                flexDirection="column"
+            >
+                {rows.map((nodes, i) => (
+                    <HashiRow key={i} nodes={nodes} />
+                ))}
+            </Box>
+            {showInstructions ? <Messages hasSolution={hasSolution} /> : null}
+        </Box>
+    )
+}

package/src/components/HashiRow.tsx

@@ -0,0 +1,94 @@
+import { Box, Text } from 'ink'
+
+import type { HashiNodeData } from '../types.ts'
+import { NODE_WIDTH, OUTER_PADDING, SPACE_BETWEEN } from './HashiGrid.tsx'
+
+type HashiRowProps = {
+    nodes: HashiNodeData[]
+}
+
+const TOP_ROW = 0
+const MIDDLE_ROW = 1
+const BOTTOM_ROW = 2
+const ROW_HEIGHT = 3
+
+/**
+ * Build the HashiGrid node with its value and borders. Options:
+ *   - node with a value (always 1 digit)
+ *   - empty node - render just spaces
+ *   - horizontal line - single and double
+ *   - vertical line - single and double
+ */
+export function constructNode(node: HashiNodeData, line: 0 | 1 | 2): string {
+    // Horizontal line
+    if (node.value === '-') {
+        return line === MIDDLE_ROW ? '─────' : ' '.repeat(NODE_WIDTH)
+    }
+
+    // Double horizontal line
+    if (node.value === '=') {
+        return line === MIDDLE_ROW ? '═════' : ' '.repeat(NODE_WIDTH)
+    }
+
+    // Vertical line
+    if (node.value === '|') {
+        return '  │  '
+    }
+
+    // Double vertical line
+    if (node.value === '#') {
+        return '  ║  '
+    }
+
+    // Node with value to render
+    if (node.value !== ' ') {
+        if (line === TOP_ROW) {
+            const up = node.lineUp === 2 ? '╨' : node.lineUp === 1 ? '┴' : '─'
+            return `╭─${up}─╮`
+        } else if (line === MIDDLE_ROW) {
+            const left = node.lineLeft === 2 ? '╡' : node.lineLeft === 1 ? '┤' : '│'
+            const right = node.lineRight === 2 ? '╞' : node.lineRight === 1 ? '├' : '│'
+            return `${left} ${node.value} ${right}`
+        } else if (line === BOTTOM_ROW) {
+            const down = node.lineDown === 2 ? '╥' : node.lineDown === 1 ? '┬' : '─'
+            return `╰─${down}─╯`
+        }
+    }
+
+    // Empty node
+    return ' '.repeat(NODE_WIDTH)
+}
+
+export default function HashiRow({ nodes }: HashiRowProps) {
+    // Each row consists of multiple lines of terminal output
+    const lines: string[] = []
+    for (let line = 0; line < ROW_HEIGHT; line++) {
+        let rowStr = ' '.repeat(OUTER_PADDING)
+
+        // Render each node into the terminal line output
+        for (let i = 0; i < nodes.length; i++) {
+            const node = nodes[i]
+            if (!node) {
+                rowStr += ' '.repeat(NODE_WIDTH)
+                continue
+            }
+
+            rowStr += constructNode(node, line as 0 | 1 | 2)
+
+            // Add space between columns except the last
+            if (i < nodes.length - 1) {
+                rowStr += ' '.repeat(SPACE_BETWEEN)
+            }
+        }
+        rowStr += ' '.repeat(OUTER_PADDING)
+        lines.push(rowStr)
+    }
+
+    return (
+        <Box flexDirection="column">
+            {lines.map((line, i) => (
+                <Text key={i}>{line}</Text>
+            ))}
+        </Box>
+    )
+}

package/src/components/Header.tsx

@@ -0,0 +1,25 @@
+import { Box, Text } from 'ink'
+
+type HeaderProps = {
+    puzzleIndex: number
+    puzzle: string
+    isCustomPuzzle?: boolean
+    showSolution?: boolean
+}
+
+export default function Header({
+    puzzleIndex,
+    puzzle,
+    isCustomPuzzle = false,
+    showSolution = false,
+}: HeaderProps) {
+    const title = isCustomPuzzle
+        ? `Bridges: Puzzle - ${puzzle}`
+        : `Bridges: Puzzle #${puzzleIndex + 1}${showSolution ? ' (Solution)' : ''}`
+
+    return (
+        <Box marginBottom={1}>
+            <Text bold>{title}</Text>
+        </Box>
+    )
+}

package/src/components/Messages.tsx

@@ -0,0 +1,34 @@
+import { Box, Text } from 'ink'
+
+type LegendItem = {
+    key: string
+    description: string
+    disabled?: boolean
+}
+
+const LEGEND_ITEMS = (hasSolution: boolean): LegendItem[] => [
+    { key: 'p', description: 'Previous puzzle' },
+    { key: 'n', description: 'Next puzzle' },
+    { key: 's', description: 'Show solution', disabled: !hasSolution },
+    { key: 'q', description: 'Quit' },
+]
+
+type MessagesProps = {
+    hasSolution?: boolean
+}
+
+export default function Messages({ hasSolution = false }: MessagesProps) {
+    return (
+        <Box flexDirection="column" marginTop={1}>
+            <Text bold>Controls:</Text>
+            {LEGEND_ITEMS(hasSolution).map(item => (
+                <Box key={item.key}>
+                    <Text bold color={item.disabled ? 'gray' : undefined}>
+                        {item.key}
+                    </Text>
+                    <Text color={item.disabled ? 'gray' : undefined}>: {item.description}</Text>
+                </Box>
+            ))}
+        </Box>
+    )
+}

package/src/components/__tests__/HashiGrid.test.tsx

@@ -0,0 +1,55 @@
+import { render } from 'ink-testing-library'
+import { describe, expect, it } from 'vitest'
+
+import HashiGrid from '../HashiGrid.tsx'
+
+describe('HashiGrid', () => {
+    it('renders multiple rows', () => {
+        const { lastFrame } = render(
+            <HashiGrid
+                numNodes={5}
+                rows={[
+                    [{ value: 3 }, { value: ' ' }, { value: 2 }, { value: ' ' }, { value: ' ' }],
+                    [{ value: ' ' }, { value: 1 }, { value: 3 }, { value: 2 }, { value: ' ' }],
+                    [{ value: ' ' }, { value: ' ' }, { value: ' ' }, { value: 1 }, { value: 1 }],
+                    [{ value: 4 }, { value: ' ' }, { value: ' ' }, { value: ' ' }, { value: 3 }],
+                ]}
+            />
+        )
+
+        expect(lastFrame()).toEqual(
+            `Bridges: Puzzle #1
+
+┌───────────────────────────┐
+│ ╭───╮     ╭───╮           │
+│ │ 3 │     │ 2 │           │
+│ ╰───╯     ╰───╯           │
+│      ╭───╮╭───╮╭───╮      │
+│      │ 1 ││ 3 ││ 2 │      │
+│      ╰───╯╰───╯╰───╯      │
+│                ╭───╮╭───╮ │
+│                │ 1 ││ 1 │ │
+│                ╰───╯╰───╯ │
+│ ╭───╮               ╭───╮ │
+│ │ 4 │               │ 3 │ │
+│ ╰───╯               ╰───╯ │
+└───────────────────────────┘`
+        )
+    })
+
+    describe('grid data validation', () => {
+        it('throws if row length does not match numNodes', () => {
+            const { lastFrame } = render(
+                <HashiGrid numNodes={3} rows={[[{ value: 1 }, { value: ' ' }]]} />
+            )
+            expect(lastFrame()).toContain('expected 3 nodes, got 2')
+        })
+
+        it('throws if node value is invalid', () => {
+            const { lastFrame } = render(
+                <HashiGrid numNodes={1} rows={[[{ value: 'invalid' } as never]]} />
+            )
+            expect(lastFrame()).toContain('invalid value')
+        })
+    })
+})

package/src/components/__tests__/HashiRow.test.tsx

@@ -0,0 +1,155 @@
+import { render } from 'ink-testing-library'
+import { describe, expect, it } from 'vitest'
+
+import type { HashiNodeData } from '../../types.ts'
+import HashiRow, { constructNode } from '../HashiRow.tsx'
+
+describe('constructNode()', () => {
+    describe('empty node', () => {
+        it('renders space value with no lines', () => {
+            const node: HashiNodeData = { value: ' ' }
+            expect(constructNode(node, 0)).toEqual('     ')
+            expect(constructNode(node, 1)).toEqual('     ')
+            expect(constructNode(node, 2)).toEqual('     ')
+        })
+    })
+
+    describe('horizontal line node', () => {
+        it('renders a horizontal line in the middle', () => {
+            const node: HashiNodeData = { value: '-' }
+            expect(constructNode(node, 0)).toEqual('     ')
+            expect(constructNode(node, 1)).toEqual('─────')
+            expect(constructNode(node, 2)).toEqual('     ')
+        })
+
+        it('renders a double horizontal line in the middle', () => {
+            const node: HashiNodeData = { value: '=' }
+            expect(constructNode(node, 0)).toEqual('     ')
+            expect(constructNode(node, 1)).toEqual('═════')
+            expect(constructNode(node, 2)).toEqual('     ')
+        })
+    })
+
+    describe('vertical line node', () => {
+        it('renders a vertical line in the center', () => {
+            const node: HashiNodeData = { value: '|' }
+            expect(constructNode(node, 0)).toEqual('  │  ')
+            expect(constructNode(node, 1)).toEqual('  │  ')
+            expect(constructNode(node, 2)).toEqual('  │  ')
+        })
+
+        it('renders a double vertical line in the center', () => {
+            const node: HashiNodeData = { value: '#' }
+            expect(constructNode(node, 0)).toEqual('  ║  ')
+            expect(constructNode(node, 1)).toEqual('  ║  ')
+            expect(constructNode(node, 2)).toEqual('  ║  ')
+        })
+    })
+
+    describe('node with value', () => {
+        describe('TOP_ROW', () => {
+            it('renders top border', () => {
+                const node: HashiNodeData = { value: 5 }
+                expect(constructNode(node, 0)).toEqual('╭───╮')
+            })
+
+            it('renders border with vertical line up', () => {
+                const node: HashiNodeData = { value: 5, lineUp: 1 }
+                expect(constructNode(node, 0)).toEqual('╭─┴─╮')
+            })
+
+            it('renders border with double vertical line up', () => {
+                const node: HashiNodeData = { value: 5, lineUp: 2 }
+                expect(constructNode(node, 0)).toEqual('╭─╨─╮')
+            })
+        })
+
+        describe('MIDDLE_ROW', () => {
+            it('renders middle row - value with vertical borders', () => {
+                const node: HashiNodeData = { value: 5 }
+                expect(constructNode(node, 1)).toEqual('│ 5 │')
+            })
+
+            it('renders value with horizontal line on left', () => {
+                const node: HashiNodeData = { value: 5, lineLeft: 1 }
+                expect(constructNode(node, 1)).toEqual('┤ 5 │')
+            })
+
+            it('renders value with horizontal line on right', () => {
+                const node: HashiNodeData = { value: 5, lineRight: 1 }
+                expect(constructNode(node, 1)).toEqual('│ 5 ├')
+            })
+
+            it('renders value with horizontal lines on both sides', () => {
+                const node: HashiNodeData = { value: 5, lineLeft: 1, lineRight: 1 }
+                expect(constructNode(node, 1)).toEqual('┤ 5 ├')
+            })
+
+            it('renders value with double horizontal lines on both sides', () => {
+                const node: HashiNodeData = { value: 5, lineLeft: 2, lineRight: 2 }
+                expect(constructNode(node, 1)).toEqual('╡ 5 ╞')
+            })
+        })
+
+        describe('BOTTOM_ROW', () => {
+            it('renders bottom border without lines', () => {
+                const node: HashiNodeData = { value: 5 }
+                expect(constructNode(node, 2)).toEqual('╰───╯')
+            })
+
+            it('renders border with vertical line down', () => {
+                const node: HashiNodeData = { value: 5, lineDown: 1 }
+                expect(constructNode(node, 2)).toEqual('╰─┬─╯')
+            })
+
+            it('renders border with double vertical line down', () => {
+                const node: HashiNodeData = { value: 5, lineDown: 2 }
+                expect(constructNode(node, 2)).toEqual('╰─╥─╯')
+            })
+        })
+    })
+})
+
+describe('HashiRow component', () => {
+    it('renders three nodes', () => {
+        const { lastFrame } = render(
+            <HashiRow nodes={[{ value: 1 }, { value: 2 }, { value: 3 }]} />
+        )
+        expect(lastFrame()).toEqual(
+            ` ╭───╮╭───╮╭───╮
+ │ 1 ││ 2 ││ 3 │
+ ╰───╯╰───╯╰───╯`
+        )
+    })
+
+    it('renders nodes connected horizontally', () => {
+        const { lastFrame } = render(
+            <HashiRow
+                nodes={[{ value: 1, lineRight: 1 }, { value: '-' }, { value: 3, lineLeft: 1 }]}
+            />
+        )
+        expect(lastFrame()).toEqual(` ╭───╮     ╭───╮
+ │ 1 ├─────┤ 3 │
+ ╰───╯     ╰───╯`)
+    })
+
+    it('renders a vertical node', () => {
+        const { lastFrame } = render(
+            <HashiRow nodes={[{ value: 1 }, { value: '|' }, { value: 3 }]} />
+        )
+        expect(lastFrame()).toEqual(` ╭───╮  │  ╭───╮
+ │ 1 │  │  │ 3 │
+ ╰───╯  │  ╰───╯`)
+    })
+
+    it('renders empty positions as spaces', () => {
+        const { lastFrame } = render(
+            <HashiRow nodes={[{ value: 1 }, { value: ' ' }, { value: 3 }]} />
+        )
+        expect(lastFrame()).toEqual(
+            ` ╭───╮     ╭───╮
+ │ 1 │     │ 3 │
+ ╰───╯     ╰───╯`
+        )
+    })
+})

package/src/components/__tests__/Messages.test.tsx

@@ -0,0 +1,14 @@
+import { render } from 'ink-testing-library'
+import { describe, expect, it } from 'vitest'
+
+import Messages from '../Messages.tsx'
+
+describe('Messages', () => {
+    it('renders the legend', () => {
+        const { lastFrame } = render(<Messages />)
+        expect(lastFrame()).toContain('Controls:')
+        expect(lastFrame()).toContain('p: Previous puzzle')
+        expect(lastFrame()).toContain('n: Next puzzle')
+        expect(lastFrame()).toContain('q: Quit')
+    })
+})