@sergenkabakci/grept 0.0.0-stage → 1.0.0

package/dist/output/formatter.js

@@ -0,0 +1,112 @@
+import { getMatchByteOffset } from '../core/offsets.js';
+export class OutputFormatter {
+    options;
+    colors;
+    constructor(options, colors) {
+        this.options = options;
+        this.colors = colors;
+    }
+    /**
+     * Formats a normal matching or context line.
+     */
+    formatLine(displayPath, showFilename, lineNum, byteOffset, text, isContext, matchRanges) {
+        const sepChar = isContext ? '-' : ':';
+        let prefix = '';
+        if (showFilename) {
+            const coloredFilename = this.colors.filename(displayPath);
+            if (this.options.nullByteFilename) {
+                prefix += coloredFilename + '\0';
+            }
+            else {
+                prefix += coloredFilename + this.colors.separator(sepChar);
+            }
+        }
+        if (this.options.lineNumber) {
+            const numStr = String(lineNum);
+            prefix += this.colors.lineNumber(numStr) + this.colors.separator(sepChar);
+        }
+        if (this.options.byteOffset) {
+            const offsetStr = String(byteOffset);
+            prefix += this.colors.byteOffset(offsetStr) + this.colors.separator(sepChar);
+        }
+        if (this.options.initialTab && prefix.length > 0) {
+            prefix += '\t';
+        }
+        // Apply color highlighting to matched text if not context
+        let formattedText = text;
+        if (!isContext && matchRanges.length > 0) {
+            formattedText = this.highlightMatches(text, matchRanges);
+        }
+        return prefix + formattedText;
+    }
+    /**
+     * Formats only-matching (-o) output lines.
+     */
+    formatOnlyMatching(displayPath, showFilename, lineNum, lineByteOffset, lineText, matches) {
+        const lines = [];
+        const sepChar = ':';
+        for (const m of matches) {
+            if (m.text.length === 0)
+                continue; // GNU grep ignores empty matches with -o
+            let prefix = '';
+            if (showFilename) {
+                const coloredFilename = this.colors.filename(displayPath);
+                if (this.options.nullByteFilename) {
+                    prefix += coloredFilename + '\0';
+                }
+                else {
+                    prefix += coloredFilename + this.colors.separator(sepChar);
+                }
+            }
+            if (this.options.lineNumber) {
+                prefix += this.colors.lineNumber(String(lineNum)) + this.colors.separator(sepChar);
+            }
+            if (this.options.byteOffset) {
+                const matchByteOffset = getMatchByteOffset(lineByteOffset, lineText, m.start);
+                prefix += this.colors.byteOffset(String(matchByteOffset)) + this.colors.separator(sepChar);
+            }
+            if (this.options.initialTab && prefix.length > 0) {
+                prefix += '\t';
+            }
+            const matchText = this.colors.matchedText(m.text);
+            lines.push(prefix + matchText);
+        }
+        return lines;
+    }
+    /**
+     * Highlights match ranges inside text using ANSI sequences.
+     */
+    highlightMatches(text, ranges) {
+        let result = '';
+        let lastIdx = 0;
+        for (const r of ranges) {
+            if (r.start > lastIdx) {
+                result += text.slice(lastIdx, r.start);
+            }
+            result += this.colors.matchedText(text.slice(r.start, r.end));
+            lastIdx = Math.max(lastIdx, r.end);
+        }
+        if (lastIdx < text.length) {
+            result += text.slice(lastIdx);
+        }
+        return result;
+    }
+    formatBinaryMatch(displayPath) {
+        return `Binary file ${displayPath} matches`;
+    }
+    formatCount(displayPath, showFilename, count) {
+        if (showFilename) {
+            if (this.options.nullByteFilename) {
+                return `${this.colors.filename(displayPath)}\0${count}`;
+            }
+            return `${this.colors.filename(displayPath)}:${count}`;
+        }
+        return String(count);
+    }
+    formatGroupSeparator() {
+        if (this.options.groupSeparator === null)
+            return null;
+        return this.colors.groupSeparator(this.options.groupSeparator);
+    }
+}
+//# sourceMappingURL=formatter.js.map

package/dist/output/formatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatter.js","sourceRoot":"","sources":["../../src/output/formatter.ts"],"names":[],"mappings":"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"}

package/dist/output/writer.d.ts

@@ -0,0 +1,10 @@
+export declare class OutputWriter {
+    private stdout;
+    private stderr;
+    private nullData;
+    readonly lineBuffered: boolean;
+    constructor(stdout?: NodeJS.WriteStream, stderr?: NodeJS.WriteStream, nullData?: boolean, lineBuffered?: boolean);
+    writeLine(line: string): void;
+    writeError(message: string): void;
+}
+//# sourceMappingURL=writer.d.ts.map

package/dist/output/writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.d.ts","sourceRoot":"","sources":["../../src/output/writer.ts"],"names":[],"mappings":"AAsBA,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,QAAQ,CAAU;IAC1B,SAAgB,YAAY,EAAE,OAAO,CAAC;gBAGpC,MAAM,GAAE,MAAM,CAAC,WAA4B,EAC3C,MAAM,GAAE,MAAM,CAAC,WAA4B,EAC3C,QAAQ,UAAQ,EAChB,YAAY,UAAQ;IAUtB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAgB7B,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;CAWlC"}

package/dist/output/writer.js

@@ -0,0 +1,62 @@
+let pipeHandlersInstalled = false;
+function ensurePipeHandlersInstalled() {
+    if (pipeHandlersInstalled)
+        return;
+    pipeHandlersInstalled = true;
+    if (process.stdout && typeof process.stdout.on === 'function') {
+        process.stdout.on('error', (err) => {
+            if (err.code === 'EPIPE') {
+                process.exit(0);
+            }
+        });
+    }
+    if (process.stderr && typeof process.stderr.on === 'function') {
+        process.stderr.on('error', (err) => {
+            if (err.code === 'EPIPE') {
+                process.exit(0);
+            }
+        });
+    }
+}
+export class OutputWriter {
+    stdout;
+    stderr;
+    nullData;
+    lineBuffered;
+    constructor(stdout = process.stdout, stderr = process.stderr, nullData = false, lineBuffered = false) {
+        this.stdout = stdout;
+        this.stderr = stderr;
+        this.nullData = nullData;
+        this.lineBuffered = lineBuffered;
+        ensurePipeHandlersInstalled();
+    }
+    writeLine(line) {
+        const endChar = this.nullData ? '\0' : '\n';
+        try {
+            this.stdout.write(line + endChar);
+            if (this.lineBuffered && typeof this.stdout.uncork === 'function') {
+                this.stdout.uncork();
+            }
+        }
+        catch (err) {
+            const code = err?.code;
+            if (code === 'EPIPE') {
+                process.exit(0);
+            }
+            throw err;
+        }
+    }
+    writeError(message) {
+        try {
+            this.stderr.write(message + '\n');
+        }
+        catch (err) {
+            const code = err?.code;
+            if (code === 'EPIPE') {
+                process.exit(0);
+            }
+            throw err;
+        }
+    }
+}
+//# sourceMappingURL=writer.js.map

package/dist/output/writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.js","sourceRoot":"","sources":["../../src/output/writer.ts"],"names":[],"mappings":"AAAA,IAAI,qBAAqB,GAAG,KAAK,CAAC;AAElC,SAAS,2BAA2B;IAClC,IAAI,qBAAqB;QAAE,OAAO;IAClC,qBAAqB,GAAG,IAAI,CAAC;IAE7B,IAAI,OAAO,CAAC,MAAM,IAAI,OAAO,OAAO,CAAC,MAAM,CAAC,EAAE,KAAK,UAAU,EAAE,CAAC;QAC9D,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAA0B,EAAE,EAAE;YACxD,IAAI,GAAG,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;gBACzB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAClB,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,IAAI,OAAO,OAAO,CAAC,MAAM,CAAC,EAAE,KAAK,UAAU,EAAE,CAAC;QAC9D,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAA0B,EAAE,EAAE;YACxD,IAAI,GAAG,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;gBACzB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAClB,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED,MAAM,OAAO,YAAY;IACf,MAAM,CAAqB;IAC3B,MAAM,CAAqB;IAC3B,QAAQ,CAAU;IACV,YAAY,CAAU;IAEtC,YACE,SAA6B,OAAO,CAAC,MAAM,EAC3C,SAA6B,OAAO,CAAC,MAAM,EAC3C,QAAQ,GAAG,KAAK,EAChB,YAAY,GAAG,KAAK;QAEpB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QAEjC,2BAA2B,EAAE,CAAC;IAChC,CAAC;IAED,SAAS,CAAC,IAAY;QACpB,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;QAC5C,IAAI,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,OAAO,CAAC,CAAC;YAClC,IAAI,IAAI,CAAC,YAAY,IAAI,OAAQ,IAAI,CAAC,MAAc,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;gBAC1E,IAAI,CAAC,MAAc,CAAC,MAAM,EAAE,CAAC;YAChC,CAAC;QACH,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,MAAM,IAAI,GAAI,GAA6B,EAAE,IAAI,CAAC;YAClD,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;gBACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAClB,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IAED,UAAU,CAAC,OAAe;QACxB,IAAI,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;QACpC,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,MAAM,IAAI,GAAI,GAA6B,EAAE,IAAI,CAAC;YAClD,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;gBACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAClB,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;CACF"}

package/dist/utils/terminal.d.ts

@@ -0,0 +1,7 @@
+export type ColorChoice = 'never' | 'always' | 'auto';
+/**
+ * Determines whether color escape sequences should be output based on
+ * the user option, environment variables (NO_COLOR, TERM), and TTY status.
+ */
+export declare function shouldEnableColor(colorChoice: ColorChoice): boolean;
+//# sourceMappingURL=terminal.d.ts.map

package/dist/utils/terminal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal.d.ts","sourceRoot":"","sources":["../../src/utils/terminal.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEtD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAkBnE"}

package/dist/utils/terminal.js

@@ -0,0 +1,21 @@
+/**
+ * Determines whether color escape sequences should be output based on
+ * the user option, environment variables (NO_COLOR, TERM), and TTY status.
+ */
+export function shouldEnableColor(colorChoice) {
+    if (colorChoice === 'never') {
+        return false;
+    }
+    if (colorChoice === 'always') {
+        return true;
+    }
+    // Auto mode
+    if (process.env['NO_COLOR'] !== undefined && process.env['NO_COLOR'] !== '') {
+        return false;
+    }
+    if (process.env['TERM'] === 'dumb') {
+        return false;
+    }
+    return Boolean(process.stdout && process.stdout.isTTY);
+}
+//# sourceMappingURL=terminal.js.map

package/dist/utils/terminal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal.js","sourceRoot":"","sources":["../../src/utils/terminal.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,WAAwB;IACxD,IAAI,WAAW,KAAK,OAAO,EAAE,CAAC;QAC5B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,WAAW,KAAK,QAAQ,EAAE,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,YAAY;IACZ,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,CAAC;QAC5E,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,MAAM,EAAE,CAAC;QACnC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACzD,CAAC"}

package/dist/utils/windows-paths.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Normalizes Windows paths (slashes, casing where applicable, extended paths)
+ */
+export declare function normalizeWindowsPath(p: string): string;
+/**
+ * Checks if two paths refer to the same file or directory on Windows (case-insensitive comparison)
+ */
+export declare function pathsEqual(p1: string, p2: string): boolean;
+/**
+ * Resolves path safely, handling extended-length path prefix if needed
+ */
+export declare function resolveWindowsPath(p: string): string;
+/**
+ * Checks if a path is a UNC network path
+ */
+export declare function isUncPath(p: string): boolean;
+/**
+ * Strips extended-length path prefix for display purposes if present
+ */
+export declare function displayPath(p: string): string;
+//# sourceMappingURL=windows-paths.d.ts.map

package/dist/utils/windows-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"windows-paths.d.ts","sourceRoot":"","sources":["../../src/utils/windows-paths.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAStD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAGpD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAE5C;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ7C"}

package/dist/utils/windows-paths.js

@@ -0,0 +1,47 @@
+import path from 'node:path';
+/**
+ * Normalizes Windows paths (slashes, casing where applicable, extended paths)
+ */
+export function normalizeWindowsPath(p) {
+    if (!p)
+        return '';
+    // Standardize backslashes for Windows path operations
+    let normalized = path.normalize(p);
+    // Ensure drive letters are uppercase for consistent internal comparisons
+    if (/^[a-zA-Z]:/.test(normalized)) {
+        normalized = normalized[0].toUpperCase() + normalized.slice(1);
+    }
+    return normalized;
+}
+/**
+ * Checks if two paths refer to the same file or directory on Windows (case-insensitive comparison)
+ */
+export function pathsEqual(p1, p2) {
+    return normalizeWindowsPath(p1).toLowerCase() === normalizeWindowsPath(p2).toLowerCase();
+}
+/**
+ * Resolves path safely, handling extended-length path prefix if needed
+ */
+export function resolveWindowsPath(p) {
+    const resolved = path.resolve(p);
+    return normalizeWindowsPath(resolved);
+}
+/**
+ * Checks if a path is a UNC network path
+ */
+export function isUncPath(p) {
+    return /^\\\\[^\\/]+[\\/][^\\/]+/.test(p);
+}
+/**
+ * Strips extended-length path prefix for display purposes if present
+ */
+export function displayPath(p) {
+    if (p.startsWith('\\\\?\\UNC\\')) {
+        return '\\\\' + p.slice(8);
+    }
+    if (p.startsWith('\\\\?\\')) {
+        return p.slice(4);
+    }
+    return p;
+}
+//# sourceMappingURL=windows-paths.js.map

package/dist/utils/windows-paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"windows-paths.js","sourceRoot":"","sources":["../../src/utils/windows-paths.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,CAAS;IAC5C,IAAI,CAAC,CAAC;QAAE,OAAO,EAAE,CAAC;IAClB,sDAAsD;IACtD,IAAI,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IACnC,yEAAyE;IACzE,IAAI,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QAClC,UAAU,GAAG,UAAU,CAAC,CAAC,CAAE,CAAC,WAAW,EAAE,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAClE,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,EAAU,EAAE,EAAU;IAC/C,OAAO,oBAAoB,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,KAAK,oBAAoB,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;AAC3F,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,CAAS;IAC1C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACjC,OAAO,oBAAoB,CAAC,QAAQ,CAAC,CAAC;AACxC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,CAAS;IACjC,OAAO,0BAA0B,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAC5C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,CAAS;IACnC,IAAI,CAAC,CAAC,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC;QACjC,OAAO,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC7B,CAAC;IACD,IAAI,CAAC,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC5B,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC"}

package/docs/COMPATIBILITY.md

@@ -0,0 +1,118 @@
+# GNU grep Compatibility Matrix
+
+This document details the compatibility of `grept` with GNU `grep` (GNU grep 3.11 specification).
+Each option supported or evaluated is categorized into one of four states:
+- **Fully supported**: Matches GNU grep specification and behavior.
+- **Partially supported**: Functional on Windows with specific architectural differences documented.
+- **Unsupported**: Not implemented with technical justification.
+- **Not applicable on Windows**: Concept or option is specific to POSIX environments (e.g., POSIX device inodes or TTY ioctls not present on Win32).
+
+---
+
+## 1. Pattern Selection Options
+
+| Option | Long Option | Status | Notes / Behavioral Differences |
+| :--- | :--- | :--- | :--- |
+| `-E` | `--extended-regexp` | **Fully supported** | Interprets patterns as POSIX Extended Regular Expressions (ERE). Unescaped `?`, `+`, `{`, `}`, `\|`, `(`, `)` are special operators. |
+| `-F` | `--fixed-strings` | **Fully supported** | Interprets patterns as fixed strings (literal matching). Extremely fast multi-string matching. |
+| `-G` | `--basic-regexp` | **Fully supported** | Interprets patterns as POSIX Basic Regular Expressions (BRE, default). `?`, `+`, `{`, `}`, `\|`, `(`, `)` are literals unless escaped. |
+| `-P` | `--perl-regexp` | **Fully supported** | Interprets patterns as Perl-compatible regular expressions using WebAssembly-compiled PCRE2. Supports lookarounds, atomic groups, Unicode properties. |
+| `-e PATTERN` | `--regexp=PATTERN` | **Fully supported** | Specifies matching pattern. Multiple `-e` options are combined (logical OR). Protects patterns beginning with `-`. |
+| `-f FILE` | `--file=FILE` | **Fully supported** | Obtains patterns from file, one per line. Empty pattern lines match any input line. |
+| `-i`, `-y` | `--ignore-case` | **Fully supported** | Case-insensitive matching across ASCII and Unicode characters (including Turkish dotted/dotless I). |
+| `--no-ignore-case` | `--no-ignore-case` | **Fully supported** | Resets case-insensitive matching if previously specified. |
+| `-v` | `--invert-match` | **Fully supported** | Inverts the sense of matching, to select non-matching lines. |
+| `-w` | `--word-regexp` | **Fully supported** | Selects only those lines containing matches that form whole words (bounded by word/non-word boundaries). |
+| `-x` | `--line-regexp` | **Fully supported** | Selects only those matches that exactly match the whole line. |
+
+---
+
+## 2. Matching Control Options
+
+| Option | Long Option | Status | Notes / Behavioral Differences |
+| :--- | :--- | :--- | :--- |
+| `-m NUM` | `--max-count=NUM` | **Fully supported** | Stop reading a file after `NUM` matching lines. If context is specified, trailing context is printed. |
+| `--line-buffered` | `--line-buffered` | **Fully supported** | Flushes output after every line. Useful for real-time streaming in PowerShell and CMD pipelines. |
+| `-a` | `--text` | **Fully supported** | Process binary files as if they were text; equivalent to `--binary-files=text`. |
+| `-I` | *(none)* | **Fully supported** | Process a binary file as if it did not contain any matches; equivalent to `--binary-files=without-match`. |
+| `-U` | `--binary` | **Fully supported** | Treat input file as binary data, reading verbatim without CR/LF translation. |
+| *(none)* | `--binary-files=TYPE` | **Fully supported** | `TYPE` can be `binary`, `text`, or `without-match`. In `binary` mode, matches output `Binary file <NAME> matches`. |
+
+---
+
+## 3. General Output Control Options
+
+| Option | Long Option | Status | Notes / Behavioral Differences |
+| :--- | :--- | :--- | :--- |
+| `-c` | `--count` | **Fully supported** | Suppress normal output; instead print a count of matching lines for each input file. |
+| `--color[=WHEN]` | `--colour[=WHEN]` | **Fully supported** | `WHEN` may be `never`, `always`, or `auto`. Respects `NO_COLOR` env var and Windows Terminal / conhost capabilities. |
+| `-L` | `--files-without-match` | **Fully supported** | Suppress normal output; print the name of each input file from which no output would have normally been produced. |
+| `-l` | `--files-with-matches` | **Fully supported** | Suppress normal output; print the name of each input file with matches (stops scanning upon first match). |
+| `-o` | `--only-matching` | **Fully supported** | Print only the matched (non-empty) parts of a matching line, each on a separate output line. |
+| `-q` | `--quiet`, `--silent` | **Fully supported** | Quiet mode. Exit immediately with zero status if any match is found, even if an error was detected. |
+| `-s` | `--no-messages` | **Fully supported** | Suppress error messages about nonexistent or unreadable files. Argument errors still reported. |
+
+---
+
+## 4. Output Line Prefix Control Options
+
+| Option | Long Option | Status | Notes / Behavioral Differences |
+| :--- | :--- | :--- | :--- |
+| `-b` | `--byte-offset` | **Fully supported** | Print the 0-based byte offset within the input file before each line of output. With `-o`, prints offset of match. |
+| `-H` | `--with-filename` | **Fully supported** | Print the file name for each match. Default when searching multiple files or recursive directories. |
+| `-h` | `--no-filename` | **Fully supported** | Suppress the prefixing of file names on output. Default when searching a single file or stdin. |
+| `--label=LABEL` | *(none)* | **Fully supported** | Display input from standard input as if it came from file `LABEL`. |
+| `-n` | `--line-number` | **Fully supported** | Prefix each line of output with the 1-based line number within its input file. |
+| `-T` | `--initial-tab` | **Fully supported** | Pad prefix with a tab so that line content aligns across lines with varying number widths. |
+| `-u` | `--unix-byte-offsets` | **Fully supported** | Report Unix-style byte offsets as if the file were Unix text (CRLF `\r\n` pairs are counted as 1 byte `\n` instead of 2 bytes). Matches GNU grep on MS-Windows. |
+| `-Z` | `--null` | **Fully supported** | Output a zero byte (`NUL`) instead of the character that normally follows a file name (e.g. `:`). |
+| `-z` | `--null-data` | **Fully supported** | Treat input and output data as sequences of lines, each terminated by a zero byte (`NUL`) instead of a newline. |
+
+---
+
+## 5. Context Control Options
+
+| Option | Long Option | Status | Notes / Behavioral Differences |
+| :--- | :--- | :--- | :--- |
+| `-A NUM` | `--after-context=NUM` | **Fully supported** | Print `NUM` lines of trailing context after matching lines. Overlapping contexts are merged. |
+| `-B NUM` | `--before-context=NUM` | **Fully supported** | Print `NUM` lines of leading context before matching lines. Overlapping contexts are merged. |
+| `-C NUM`, `-NUM` | `--context=NUM` | **Fully supported** | Print `NUM` lines of leading and trailing context. |
+| *(none)* | `--group-separator=SEP` | **Fully supported** | Use `SEP` as group separator between contiguous groups of matches. Default is `--`. |
+| *(none)* | `--no-group-separator` | **Fully supported** | Suppress the group separator between contiguous groups of matches. |
+
+---
+
+## 6. File and Directory Selection Options
+
+| Option | Long Option | Status | Notes / Behavioral Differences |
+| :--- | :--- | :--- | :--- |
+| `-r` | `--recursive` | **Fully supported** | Read all files under each directory recursively. Follows symbolic links only if they are on the command line. |
+| `-R` | `--dereference-recursive` | **Fully supported** | Recurse directories and dereference directory symbolic links / NTFS junctions, with cycle detection. |
+| `--follow` | *(none)* | **Fully supported** | Follow symlinks and reparse points during traversal. |
+| `--include=GLOB` | *(none)* | **Fully supported** | Search only files whose base name matches `GLOB` (case-insensitive on Windows). |
+| `--exclude=GLOB` | *(none)* | **Fully supported** | Skip any command-line file with a name suffix that matches the pattern `GLOB`. |
+| `--exclude-from=FILE` | *(none)* | **Fully supported** | Skip files whose base name matches any of the file-name globs read from `FILE`. |
+| `--exclude-dir=GLOB` | *(none)* | **Fully supported** | Skip directories matching `GLOB`. By default skips `node_modules`, `.git`, and hidden directories. |
+| `--max-depth=NUM` | *(none)* | **Fully supported** | Descend at most `NUM` directory levels below command-line targets. |
+| `-d ACTION` | `--directories=ACTION` | **Fully supported** | If input is a directory, `ACTION` is `read`, `recurse`, or `skip`. |
+| `-D ACTION` | `--devices=ACTION` | **Fully supported** | If input file is a device, FIFO, or socket, `ACTION` can be `read` or `skip`. |
+
+---
+
+## 7. Other Options
+
+| Option | Long Option | Status | Notes / Behavioral Differences |
+| :--- | :--- | :--- | :--- |
+| `--mmap` | *(none)* | **Fully supported (no-op)** | Deprecated and ignored in GNU grep 3.8+; accepted safely without error for CLI script compatibility. |
+| `--debug` | *(none)* | **Fully supported** | Output internal debugging diagnostics regarding regex parsing, matching, and traversal. |
+| `--help` | *(none)* | **Fully supported** | Display comprehensive help message and exit with 0. |
+| `-V` | `--version` | **Fully supported** | Display version information and exit with 0. |
+
+---
+
+## Exit Status
+
+- `0`: Selected lines or matches were found.
+- `1`: No lines or matches were found.
+- `2`: An error occurred (e.g., invalid regex syntax, unreadable file without `-s`, invalid option).
+- In `-q` mode, if a match is found, exit code is always `0`.

package/docs/PERFORMANCE.md

@@ -0,0 +1,58 @@
+# Performance Architecture and Benchmarks in `grept`
+
+`grept` is engineered specifically for fast text searching on modern Windows systems with NVMe and SATA SSDs.
+
+---
+
+## 1. Architectural Highlights
+
+1. **Streaming Input Processing**:
+   - Files are read in fixed 64 KB binary chunks rather than loaded entirely into memory.
+   - Lines are parsed on-the-fly, bounding peak memory consumption regardless of file size.
+   - Dynamic buffer growth safely accommodates long lines without truncation.
+
+2. **One-Time Pattern Compilation**:
+   - Regular expressions and string matchers are compiled once during CLI startup and reused across all files and lines.
+   - For PCRE2, patterns are compiled into WebAssembly memory once per search session.
+
+3. **Fast Substring Search (`-F`)**:
+   - Literal string matching bypasses regex engines completely, using optimized substring searches.
+   - Case-insensitive literal matching converts input lines with minimal object churn.
+
+4. **Zero-Allocation Byte Offsets**:
+   - Byte offsets (`-b`) are accumulated directly from incoming buffer byte counts rather than recalculating UTF-8 character lengths from string slices.
+
+5. **Early Termination**:
+   - `-q` (`--quiet`): Terminates the process immediately upon the first match found, closing open file descriptors cleanly.
+   - `-m NUM` (`--max-count`): Halts file scanning as soon as `NUM` matching lines and their after-context are satisfied.
+   - `-l` (`--files-with-matches`): Halts scanning the current file on its first match and moves to the next file.
+
+6. **Bounded Memory Footprint**:
+   - Heap usage remains under ~15 MB even when scanning multi-gigabyte files.
+
+---
+
+## 2. Benchmark Methodology and Environment
+
+- **Host Operating System**: Windows 11 (x64)
+- **Runtime**: Node.js v22.17.1
+- **File System**: NTFS
+- **Dataset**:
+  - Synthetic ~20 MB server application log (140,000 CRLF lines).
+  - Nested directory hierarchy containing 500 TypeScript source files across 20 directories.
+
+### Benchmark Results
+
+| Scenario | Execution Time (ms) | Measured Throughput | Matches |
+| :--- | :--- | :--- | :--- |
+| **Fixed-string search (`-F`)** | ~207 ms | **95.31 MB/s** | 280 |
+| **Extended RegEx search (`-E`)** | ~200 ms | **98.67 MB/s** | 280 |
+| **Case-insensitive search (`-i`)** | ~350 ms | **56.49 MB/s** | 280 |
+| **High-density match count (`-c`)** | ~337 ms | **58.67 MB/s** | 1 (aggregated count) |
+| **Recursive 500 files (`-r --include=*.ts`)** | ~401 ms | *I/O bound* | 500 |
+| **PCRE2 lookaround search (`-P`)** | ~6.0 s | **3.25 MB/s** (WASM bridge) | 0 |
+
+### Memory Consumption
+
+- **Peak Heap Used**: 12.65 MB
+- **Peak RSS**: 154.95 MB (including Node.js V8 runtime + WASM PCRE2 binary)

package/docs/REGEX.md

@@ -0,0 +1,99 @@
+# Regular Expression Engines and Matching Semantics in `grept`
+
+`grept` supports four distinct regex and string matching modes corresponding to GNU grep:
+
+1. **Basic Regular Expressions (`-G`, `--basic-regexp`)** [Default]
+2. **Extended Regular Expressions (`-E`, `--extended-regexp`)**
+3. **Fixed Strings (`-F`, `--fixed-strings`)**
+4. **Perl-Compatible Regular Expressions (`-P`, `--perl-regexp`)**
+
+---
+
+## 1. Engine Modes
+
+### Basic Regular Expressions (BRE, `-G`)
+In GNU Basic Regular Expression mode:
+- Meta-characters `?`, `+`, `{`, `}`, `|`, `(`, and `)` are treated as ordinary literal characters.
+- To activate their special meaning, they must be backslash-escaped:
+  - `\?` : Zero or one occurrence
+  - `\+` : One or more occurrences
+  - `\{m,n\}` : Between `m` and `n` occurrences
+  - `\|` : Alternation (OR)
+  - `\(` and `\)` : Capturing groups
+- Unescaped `.` matches any character except newline (unless `-z` is enabled).
+- `^` anchors to the start of the line; `$` anchors to the end.
+- `*` matches zero or more occurrences of the preceding element.
+- Backreferences `\1` through `\9` refer back to matched groups.
+
+### Extended Regular Expressions (ERE, `-E`)
+In GNU Extended Regular Expression mode:
+- Meta-characters `?`, `+`, `{`, `}`, `|`, `(`, and `)` are special operators by default.
+- Preceding them with a backslash makes them literal characters.
+- Supports POSIX character classes and alternation without backslashes.
+
+### Fixed Strings (`-F`)
+- All characters in the pattern are treated as literal characters.
+- Fast multi-string search using direct substring matching.
+- Avoids regular expression compilation overhead.
+
+### Perl-Compatible Regular Expressions (PCRE, `-P`)
+- Backed by WebAssembly-compiled **PCRE2 (10.49+)**.
+- Zero native build dependencies; 100% portable on Windows Node.js.
+- Supports:
+  - Lookahead (`(?=...)`, `(?!...)`) and Lookbehind (`(?<=...)`, `(?<!...)`)
+  - Non-capturing groups (`(?:...)`) and Named groups (`(?P<name>...)`)
+  - Possessive quantifiers (`*+`, `++`, `?+`) and Atomic groups (`(?>...)`)
+  - Unicode character properties (`\p{...}`) and PCRE control verbs
+  - Configurable backtracking step limits for ReDoS protection.
+
+---
+
+## 2. POSIX Character Classes
+
+Both BRE and ERE support POSIX character classes within bracket expressions:
+
+| POSIX Class | Matches |
+| :--- | :--- |
+| `[:alnum:]` | Alphanumeric characters (`[0-9A-Za-z]`) |
+| `[:alpha:]` | Alphabetic characters (`[A-Za-z]`) |
+| `[:blank:]` | Space and tab characters (`[ \t]`) |
+| `[:cntrl:]` | Control characters (`[\x00-\x1F\x7F]`) |
+| `[:digit:]` | Digits (`[0-9]`) |
+| `[:graph:]` | Non-blank printable characters (`[\x21-\x7E]`) |
+| `[:lower:]` | Lowercase letters (`[a-z]`) |
+| `[:print:]` | Printable characters including space (`[\x20-\x7E]`) |
+| `[:punct:]` | Punctuation characters (`[!-/:-@[-`{-~]`) |
+| `[:space:]` | Whitespace characters (`[ \t\r\n\v\f]`) |
+| `[:upper:]` | Uppercase letters (`[A-Z]`) |
+| `[:xdigit:]` | Hexadecimal digits (`[0-9A-Fa-f]`) |
+
+---
+
+## 3. Word Boundaries and GNU Extensions
+
+- `\b` : Word boundary
+- `\B` : Non-word boundary
+- `\<` : Start of word boundary (`(?<=\W|^)(?=\w)`)
+- `\>` : End of word boundary (`(?<=\w)(?=\W|$)`)
+- `\w` : Word character (`[a-zA-Z0-9_]`)
+- `\W` : Non-word character (`[^a-zA-Z0-9_]`)
+- `\s` : Whitespace character (`[ \t\r\n\v\f]`)
+- `\S` : Non-whitespace character
+
+---
+
+## 4. Unicode and Case Folding
+
+- When `-i` (`--ignore-case`) is active, case folding applies across both ASCII and Unicode text.
+- Special handling is included for Turkish characters:
+  - Capital dotted `İ` (U+0130) and lowercase `i` (U+0069)
+  - Capital dotless `I` (U+0049) and lowercase dotless `ı` (U+0131)
+- In `-P` mode, `FLAGS.UTF` and `FLAGS.UCP` ensure full Unicode code-point matching.
+
+---
+
+## 5. Security & ReDoS Mitigation
+
+- In PCRE2 mode, execution limits (`matchLimit: 1_000_000`, `depthLimit: 10_000`) prevent runaway backtracking.
+- Empty patterns match every line (matching GNU grep behavior).
+- Invalid regular expressions emit diagnostic error messages to `stderr` and exit with code `2`.

package/docs/WINDOWS.md

@@ -0,0 +1,46 @@
+# Windows Native Filesystem & Shell Semantics in `grept`
+
+`grept` is designed from the ground up for Windows 10 and 11 environments, prioritizing NTFS characteristics, PowerShell, CMD, and Windows Terminal.
+
+---
+
+## 1. Path Handling
+
+- **Drive-Letter Paths**: Fully supports standard DOS drive paths such as `C:\Projects\App` and forward-slash normalized variants `C:/Projects/App`.
+- **Spaces in Paths**: Paths containing whitespace (e.g. `C:\Program Files\App`) are preserved without unescaping corruption.
+- **UNC Paths**: Network paths such as `\\server\share\folder` are traversed and reported correctly.
+- **Extended-Length Paths**: Paths exceeding 260 characters (`\\?\C:\Very\Deep\...`) are supported natively using Node.js filesystem APIs.
+- **Case-Insensitive Filesystem**: Windows file and directory comparisons are case-insensitive by default while preserving display casing in output.
+
+---
+
+## 2. Reparse Points, Junctions & NTFS Symlinks
+
+- **Reparse Points**: NTFS junctions (`IO_REPARSE_TAG_MOUNT_POINT`) and symbolic links are detected via `fs.lstat()`.
+- **Traversal Modes**:
+  - `-r` (`--recursive`): Recurses normal subdirectories; directory reparse points and symlinks are **not** followed unless passed as command-line arguments.
+  - `-R` (`--dereference-recursive`) or `--follow`: Traverses into directory reparse points and symlinks.
+- **Cycle Detection**:
+  - Traversal maintains a set of canonical target identifiers (`${dev}:${ino}`) and realpaths to detect loops and cyclic junctions.
+  - When a loop is detected, traversal logs a warning (suppressed by `-s`) and skips the cycle, avoiding infinite recursion.
+
+---
+
+## 3. Windows Shells & Pipelines
+
+### PowerShell (Windows PowerShell 5.1 & PowerShell 7+)
+- PowerShell cmdlets pass objects through the pipeline; when piping text to external executables, PowerShell streams UTF-8 (PowerShell 7) or ANSI/OEM (PowerShell 5.1).
+- `grept` automatically handles raw byte streams from stdin without corrupting non-ASCII characters.
+- Examples:
+  ```powershell
+  Get-Content app.log | grept "Error"
+  Get-Content -Raw data.bin | grept -z "record"
+  ```
+
+### CMD.exe
+- Pipes (`type app.log | grept "Error"`) and standard redirection (`grept "Error" < app.log > results.txt`) work seamlessly.
+
+### Console & Color Detection
+- Respects `process.stdout.isTTY` and `NO_COLOR`.
+- When output is redirected to a file or another command, ANSI color codes are automatically stripped to keep the data clean.
+- Windows Virtual Terminal processing is supported across Windows Terminal and conhost.