lines/REQUIREMENTS.md

Requirements

cli

0 001 lines FILE START optional-END prints exactly the 1-based inclusive line range from FILE, preserving selected bytes and newline boundaries without headers or decoration. [core] 0 001.e1 Usage errors, invalid ranges, unreadable files, and input read errors exit nonzero with diagnostics on stderr; errors detected before output begins must not emit stdout bytes. [errors] 0 002 Successful range output writes selected file content to stdout only; usage, diagnostics, warnings, and errors write to stderr only. [stdio] 0 003 The public argv grammar is only FILE START optional-END plus --help/-h; no regexes, shell evaluation, embedded programs, glob policy, config discovery, prompts, or formatting modes are allowed. [agent] 0 004 lines is read-only: it must not create, modify, delete, cache, page, daemonize, call the network, or persist hidden state during normal use. [safety] 1 005 lines --help documents usage, positive line-number rules, stdout/stderr boundaries, exit statuses, examples, and the read-only/no-mini-language agent boundary. [docs]

robustness

0 001 Missing arguments, invalid decimal integers, zero, overflow, END less than START, unreadable paths, and permission errors exit nonzero with a useful stderr diagnostic and no stdout bytes. [errors] 0 002 Empty files, files without a trailing newline, CRLF input, binary-ish bytes including NUL, and invalid UTF-8 are processed as bytes without text decoding or output corruption. [bytes] 0 003 Very long physical lines must not require allocating the whole line or whole file; selected bytes stream through bounded buffers. [memory] 0 004 Huge valid u64 line numbers are accepted without truncation; ranges beyond EOF succeed quietly after emitting any available selected lines. [range] 0 005 Pipeline use such as lines file 1 1000000 | head must not print noisy broken-pipe diagnostics or corrupt stdout. [pipe]

performance

0 001 Normal operation must stream or otherwise prove bounded memory: memory use is independent of file size and limited to fixed I/O buffers plus argv/path bookkeeping. [memory] 0 002 The large-file proof must generate a local file of at least 1 GiB or 10 million lines, whichever is cheaper on the machine, and record elapsed time plus peak resident memory. [bench] 0 003 For a late-file range on the large proof file, lines must target within 2x elapsed time and within 2x peak resident memory of the relevant sed -n START,ENDp or awk baseline; unavailable measurement must be reported as a blocker or reroute. [bench] 0 004 Performance work must use boring Zig/std/POSIX mechanisms first; assembly, mandatory SIMD, custom allocators, mmap-only design, background indexes, caches, or daemons are out of scope. [boring]

portability

0 001 The implementation must stay a single Zig source file plus the existing build/smoke files and avoid third-party runtime dependencies. [single] 0 002 File I/O and process behavior must use Zig standard library or portable POSIX-compatible primitives; any target-specific branch must be documented and covered by a fallback. [portable] 1 003 zig build test remains the primary verification entry point and must run through a POSIX sh smoke without GNU-only shell features. [test]

verification

1 001 zig build test proves the main output path, help text contract, invalid-input stdout cleanliness, and at least one edge case for EOF or missing trailing newline. [smoke] 1 002 A robustness smoke must cover empty files, no trailing newline, CRLF, long lines, invalid UTF-8 or binary-ish bytes, huge line numbers, END less than START, missing files, and pipeline/SIGPIPE behavior. [smoke] 1 003 A performance proof must be reproducible from repo commands, clean generated large files after completion, and report command lines, elapsed time, and peak memory for lines and the baseline. [bench]