@sergenkabakci/grept 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 grept contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,170 @@
-# Temporary Holding Version
+# `grept` — Windows-Native GNU grep-Compatible CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A production-ready, high-performance command-line text search utility designed specifically for Windows 10 and Windows 11. `grept` reproduces GNU grep's command-line interface, options, and matching semantics as closely as possible without requiring WSL, Git Bash, MSYS2, Cygwin, or native compilation.
+
+[![Windows CI](https://github.com/sergenkabakci/grept/actions/workflows/ci.yml/badge.svg)](https://github.com/sergenkabakci/grept/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Features
+
+- **GNU grep Command-Line Compatibility**: Full support for standard pattern flags, output formatting, byte offsets, context controls, and recursive traversal.
+- **Four Regex Engines**:
+  - `-G`, `--basic-regexp`: Basic Regular Expressions (GNU BRE syntax, default).
+  - `-E`, `--extended-regexp`: Extended Regular Expressions (POSIX ERE syntax).
+  - `-F`, `--fixed-strings`: High-speed literal substring matching.
+  - `-P`, `--perl-regexp`: WebAssembly-compiled PCRE2 engine supporting lookahead, lookbehind, atomic groups, and ReDoS protection.
+- **Windows-Native Semantics**:
+  - Handles DOS drive paths (`C:\...`), UNC network paths (`\\server\share\...`), and extended-length paths (`\\?\...`).
+  - Traverses NTFS file systems with cycle detection across symbolic links and NTFS junction points.
+  - Native support for Windows CRLF (`\r\n`), LF, and missing final newline endings.
+  - Case-insensitive Windows file system and glob matching.
+- **Streaming & Memory Efficiency**:
+  - 64 KB chunked streaming avoids loading entire files into memory; memory footprint remains bounded under 15 MB even on gigabyte-sized files.
+- **Accurate Byte Offsets (`-b`)**:
+  - Measures raw byte positions in the input stream (properly accounting for multi-byte UTF-8 sequences and CRLF delimiters).
+- **PowerShell and CMD Pipeline Integration**:
+  - Streams data cleanly through PowerShell (`Get-Content app.log | grept "error"`) and CMD (`type app.log | grept "error"`).
+- **Zero Native Build Dependencies**:
+  - Written in TypeScript and runs on Node.js 20+; uses pure WebAssembly for PCRE2.
+
+---
+
+## Installation
+
+### Global Installation
+```powershell
+npm install -g @sergenkabakci/grept
+```
+Once installed globally, you can invoke the CLI directly as `grept`.
+
+### On-Demand Execution (No install required)
+```powershell
+npx @sergenkabakci/grept --version
+```
+
+---
+
+## Usage Examples
+
+### Tested PowerShell Examples
+```powershell
+# Basic search in a log file
+grept "error" app.log
+
+# Case-insensitive search with line numbers
+grept -in "exception" app.log
+
+# Recursive search from current directory
+grept -rn "TODO" .
+
+# Recursive search restricted to TypeScript files
+grept -rn --include="*.ts" "useEffect" src
+
+# Exclude directories from recursive search
+grept -rn --exclude-dir=node_modules --exclude-dir=.git "TODO" .
+
+# Output 3 lines of context around matches
+grept -n -C 3 "Exception" app.log
+
+# Extended regular expression search
+grept -E "ERROR|WARNING|CRITICAL" app.log
+
+# Fixed string search with Windows paths containing spaces
+grept -F "C:\Program Files" config.txt
+
+# List only files containing matches
+grept -l "database" *.log
+
+# Count total matching lines
+grept -c "ERROR" *.log
+
+# Pipeline search from PowerShell Get-Content
+Get-Content app.log | grept "error"
+
+# Null-delimited data search
+Get-Content -Raw app.log | grept -z "error"
+```
+
+---
+
+## Option Reference
+
+### Pattern Selection
+- `-E`, `--extended-regexp`: Interpret patterns as extended regular expressions.
+- `-F`, `--fixed-strings`: Interpret patterns as fixed strings.
+- `-G`, `--basic-regexp`: Interpret patterns as basic regular expressions (default).
+- `-P`, `--perl-regexp`: Interpret patterns as Perl-compatible regular expressions (PCRE2).
+- `-e PATTERN`, `--regexp=PATTERN`: Specify matching pattern (can be used multiple times).
+- `-f FILE`, `--file=FILE`: Read patterns from file, one per line.
+- `-i`, `--ignore-case`: Case-insensitive matching (including Turkish `İ`/`i` and `I`/`ı`).
+- `-v`, `--invert-match`: Select non-matching lines.
+- `-w`, `--word-regexp`: Match only whole words.
+- `-x`, `--line-regexp`: Match only entire lines.
+
+### Matching Control
+- `-m NUM`, `--max-count=NUM`: Stop after `NUM` selected lines.
+- `--line-buffered`: Flush output on every line.
+- `-a`, `--text`: Process binary files as text.
+- `-I`: Ignore binary files (treat as non-matching).
+- `--binary-files=TYPE`: Specify binary handling (`binary`, `text`, `without-match`).
+
+### Output Control
+- `-b`, `--byte-offset`: Print 0-based byte offset of each output line.
+- `-n`, `--line-number`: Print 1-based line number.
+- `-H`, `--with-filename`: Print filename prefix for each match.
+- `-h`, `--no-filename`: Suppress filename prefix.
+- `--label=LABEL`: Use `LABEL` as standard input filename prefix.
+- `-o`, `--only-matching`: Print only matching parts of lines.
+- `-q`, `--quiet`, `--silent`: Exit immediately with status 0 upon finding a match.
+- `-s`, `--no-messages`: Suppress error messages for nonexistent or unreadable files.
+- `-c`, `--count`: Output only count of matching lines per file.
+- `-l`, `--files-with-matches`: Output filenames of files containing matches.
+- `-L`, `--files-without-match`: Output filenames of files containing no matches.
+- `-Z`, `--null`: Print NUL (`\0`) byte instead of colon after filename.
+- `-z`, `--null-data`: Input and output lines end in NUL byte instead of newline.
+- `-T`, `--initial-tab`: Align output lines using a leading tab.
+- `--color[=WHEN]`: Highlight matches (`never`, `always`, `auto`).
+
+### Context Control
+- `-B NUM`, `--before-context=NUM`: Print `NUM` lines of leading context.
+- `-A NUM`, `--after-context=NUM`: Print `NUM` lines of trailing context.
+- `-C NUM`, `--context=NUM`, `-NUM`: Print `NUM` lines of before and after context.
+- `--group-separator=SEP`: Context group separator (default `--`).
+- `--no-group-separator`: Suppress group separator.
+
+### File and Directory Selection
+- `-r`, `--recursive`: Recurse subdirectories (does not follow directory symlinks/junctions).
+- `-R`, `--dereference-recursive`: Recurse subdirectories and dereference directory symlinks/junctions.
+- `--follow`: Follow directory symlinks and reparse points.
+- `--include=GLOB`: Search only files matching `GLOB`.
+- `--exclude=GLOB`: Skip files matching `GLOB`.
+- `--exclude-from=FILE`: Skip files matching glob patterns read from `FILE`.
+- `--exclude-dir=GLOB`: Skip directories matching `GLOB`.
+- `--max-depth=NUM`: Limit traversal to `NUM` directory levels.
+- `-d ACTION`, `--directories=ACTION`: Directory handling (`read`, `recurse`, `skip`).
+- `-D ACTION`, `--devices=ACTION`: Device handling (`read`, `skip`).
+
+---
+
+## Exit Codes
+
+- `0`: One or more selected lines or matches were found.
+- `1`: No lines were selected.
+- `2`: An error occurred (e.g. invalid regex syntax, unreadable file without `-s`).
+
+---
+
+## Detailed Documentation
+
+- [GNU grep Compatibility Matrix](docs/COMPATIBILITY.md)
+- [Regex Engines & Matching Semantics](docs/REGEX.md)
+- [Windows File System & Shell Notes](docs/WINDOWS.md)
+- [Performance Architecture & Benchmarks](docs/PERFORMANCE.md)
+
+---
+
+## License
+
+MIT © [grept contributors](LICENSE)

package/bin/grept.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/index.js';

package/dist/cli/args.d.ts

@@ -0,0 +1,50 @@
+import type { ColorChoice } from '../utils/terminal.js';
+export type RegexMode = 'basic' | 'extended' | 'fixed' | 'pcre';
+export type BinaryMode = 'binary' | 'text' | 'without-match';
+export type DirectoryAction = 'read' | 'recurse' | 'skip';
+export type DeviceAction = 'read' | 'skip';
+export interface CliOptions {
+    regexMode: RegexMode;
+    ignoreCase: boolean;
+    invertMatch: boolean;
+    wordRegexp: boolean;
+    lineRegexp: boolean;
+    patterns: string[];
+    patternFiles: string[];
+    maxCount?: number;
+    byteOffset: boolean;
+    lineNumber: boolean;
+    withFilename?: boolean;
+    label?: string;
+    onlyMatching: boolean;
+    quiet: boolean;
+    noMessages: boolean;
+    count: boolean;
+    filesWithMatches: boolean;
+    filesWithoutMatch: boolean;
+    initialTab: boolean;
+    nullByteFilename: boolean;
+    nullData: boolean;
+    lineBuffered: boolean;
+    color: ColorChoice;
+    unixByteOffsets: boolean;
+    binaryFiles: BinaryMode;
+    beforeContext: number;
+    afterContext: number;
+    groupSeparator: string | null;
+    recursive: boolean;
+    dereferenceRecursive: boolean;
+    includes: string[];
+    excludes: string[];
+    excludeFrom: string[];
+    excludeDirs: string[];
+    maxDepth?: number;
+    directories: DirectoryAction;
+    devices: DeviceAction;
+    debug: boolean;
+    help: boolean;
+    version: boolean;
+    targets: string[];
+}
+export declare function parseArgs(rawArgs: string[]): CliOptions;
+//# sourceMappingURL=args.d.ts.map

package/dist/cli/args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,UAAU,GAAG,OAAO,GAAG,MAAM,CAAC;AAChE,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,MAAM,GAAG,eAAe,CAAC;AAC7D,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;AAC1D,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,CAAC;AAE3C,MAAM,WAAW,UAAU;IAEzB,SAAS,EAAE,SAAS,CAAC;IAGrB,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IAGpB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,YAAY,EAAE,MAAM,EAAE,CAAC;IAGvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,OAAO,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,OAAO,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;IACf,gBAAgB,EAAE,OAAO,CAAC;IAC1B,iBAAiB,EAAE,OAAO,CAAC;IAC3B,UAAU,EAAE,OAAO,CAAC;IACpB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,QAAQ,EAAE,OAAO,CAAC;IAClB,YAAY,EAAE,OAAO,CAAC;IACtB,KAAK,EAAE,WAAW,CAAC;IACnB,eAAe,EAAE,OAAO,CAAC;IAGzB,WAAW,EAAE,UAAU,CAAC;IAGxB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAG9B,SAAS,EAAE,OAAO,CAAC;IACnB,oBAAoB,EAAE,OAAO,CAAC;IAC9B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,eAAe,CAAC;IAC7B,OAAO,EAAE,YAAY,CAAC;IAGtB,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IAGjB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,UAAU,CAyfvD"}