@marianmeres/condition-parser 1.7.4 → 1.8.0

package/AGENTS.md

@@ -3,7 +3,7 @@
 ## Package Overview
 
 - **Name**: `@marianmeres/condition-parser`
-- **Version**: 1.7.1
+- **Version**: 1.8.0 (pending release; see deno.json for current)
 - **Purpose**: Human-friendly search conditions notation parser (Gmail-style search syntax)
 - **License**: MIT
 - **Runtime**: Deno (primary), Node.js (via NPM distribution)
@@ -13,13 +13,15 @@
 ```
 src/
 ├── mod.ts          # Public entry point (re-exports parser.ts)
-└── parser.ts       # Main parser implementation (705 lines)
+└── parser.ts       # Main parser implementation
 
 tests/
-└── all.test.ts     # Test suite (682 lines, 30 tests)
+└── all.test.ts     # Test suite (51 tests)
 
 scripts/
 └── build-npm.ts    # NPM distribution builder
+
+mcp.ts              # MCP tool definitions (parse-condition, validate-condition-syntax)
 ```
 
 ## Public API
@@ -65,12 +67,13 @@ interface ConditionParserResult {
   parsed: ConditionDump;        // from @marianmeres/condition-builder
   unparsed: string;
   meta: Meta;
+  errors: ParseError[];         // empty when input parsed cleanly
 }
 
 interface Meta {
   keys: string[];
   operators: string[];
-  values: any[];
+  values: string[];
   expressions: ExpressionData[];
 }
 
@@ -79,6 +82,12 @@ interface ExpressionData {
   operator: string;
   value: string;
 }
+
+interface ParseError {
+  message: string;
+  position: number;
+  snippet: string;
+}
 ```
 
 ## Parser Grammar
@@ -139,12 +148,22 @@ deno task release minor # Minor version release
 ## Key Implementation Details
 
 1. **Recursive Descent Parser**: Layered parsing methods handle grammar levels
-2. **Fault Tolerance**: Parse errors don't throw; unparsable content preserved in `unparsed`
-3. **Escape Support**: Backslash escapes for `'`, `"`, `:`, `)` within strings
+2. **Fault Tolerance**: Parse errors don't throw; unparsable content preserved in `unparsed` (both leading and trailing free text around a contiguous parseable middle, single-space joined); diagnostics in `errors[]`
+3. **Escape Support**: Context-dependent backslash escapes (see table below)
 4. **Case Insensitive**: Operators `and`, `or`, `not` are case-insensitive
 5. **Metadata Collection**: Unique keys, operators, values tracked in `meta`
 6. **Transform Pipeline**: Optional expression transformation before output
-7. **Pre-add Hook**: Optional filtering/routing of expressions
+7. **Pre-add Hook**: Optional filtering/routing of expressions; falsy return **drops** the expression
+
+### Escape Table
+
+| Context | Escapable characters |
+|---------|----------------------|
+| Quoted string (`"..."` / `'...'`) | `\\`, matching quote (`\"` or `\'`) |
+| Parenthesized value (`(...)`) | `\\`, `\(`, `\)` (also supports balanced nested parens literally) |
+| Unquoted token | `\\`, `\:`, `\(`, `\)`, `\ ` (space), `\⇥` (tab) |
+
+Stray backslashes (not followed by an escapable char) are preserved literally.
 
 ## Integration Pattern
 
@@ -158,17 +177,18 @@ const condition = Condition.restore(parsed);
 
 ## Test Coverage
 
-30 tests covering:
+51 tests covering:
 - Basic expression parsing
 - Quoted identifiers (single/double quotes)
-- Escaped characters
+- Escaped characters (including `\\` self-escape)
 - Logical operators (and, or, and not, or not)
-- Parenthesized grouping
-- Nested conditions
-- Free text handling
+- Parenthesized grouping (including double-wrapped `((...))`)
+- Nested parens inside values
+- `not` disambiguation (only a suffix right after and/or)
+- Free text handling (leading, trailing, and wrapped around parseable middle)
 - Transform function
-- Pre-add hook
-- Error handling
+- Pre-add hook (drop semantics + operator transfer + empty-group collapse)
+- `errors[]` diagnostic channel
 - Metadata collection
 
 ## Error Handling
@@ -177,7 +197,8 @@ Parser is fault-tolerant:
 - Malformed input doesn't throw exceptions
 - Partially parsed content preserved in `parsed`
 - Unparsable remainder preserved in `unparsed`
-- Error positions tracked internally for debugging
+- Diagnostic records available in `errors: ParseError[]`
+- For **strict validation** check `errors.length === 0 && !unparsed.trim()`
 
 ## Common Tasks
 
@@ -193,9 +214,25 @@ ConditionParser.parse(input, {
 ```
 
 ### Routing expressions
-Use `preAddHook` to filter or route expressions:
+Use `preAddHook` to filter or route expressions. A falsy return **drops** the expression from `parsed` — its "join to next" operator is transferred to the predecessor and empty groups collapse.
 ```typescript
 ConditionParser.parse(input, {
   preAddHook: (ctx) => ctx.key === "special" ? null : ctx
 });
 ```
+
+## Breaking Changes (1.8.0)
+
+When working on consumers of this package, be aware:
+
+1. `preAddHook` falsy return now **drops** the expression (was: silently substituted `1=1` placeholder).
+2. `ConditionParserResult` has a new required field `errors: ParseError[]`.
+3. `Meta.values` typed `string[]` (was `any[]`); runtime unchanged.
+4. Balanced double-wrapped `((foo:bar))` no longer produces a phantom swallowed error.
+5. Stray `not` inside later terms no longer captures the cursor (preserves preceding expressions).
+6. Quoted and parenthesized values support `\\` (literal backslash) escape.
+7. Parenthesized values preserve balanced nested parens literally: `key:(a(b)c)` → `a(b)c`.
+8. Unquoted tokens accept more escape sequences (`\\`, `\:`, `\(`, `\)`, `\ `, `\⇥`).
+9. Empty `defaultOperator` falls back to `ConditionParser.DEFAULT_OPERATOR`.
+
+See [API.md#breaking-changes](./API.md#breaking-changes) for migration notes.

package/API.md

@@ -12,6 +12,8 @@ Complete API documentation for `@marianmeres/condition-parser`.
   - [ConditionParserResult](#conditionparserresult)
   - [Meta](#meta)
   - [ExpressionData](#expressiondata)
+  - [ParseError](#parseerror)
+- [Breaking Changes](#breaking-changes)
 
 ---
 
@@ -33,6 +35,8 @@ static DEFAULT_OPERATOR: string = "eq"
 
 Default operator used when none is specified in the expression (e.g., `key:value` uses `"eq"`).
 
+> **Note**: this static is writable for convenience but affects every subsequent `parse()` call in the process. Prefer the per-call `defaultOperator` option in long-lived processes (servers, CLIs).
+
 #### `DEBUG`
 
 ```ts
@@ -41,6 +45,8 @@ static DEBUG: boolean = false
 
 Global debug flag. When `true`, all parser instances log debug information to the console.
 
+> **Note**: same caveat as `DEFAULT_OPERATOR` — prefer the per-call `debug` option.
+
 ---
 
 ### Static Methods
@@ -147,10 +153,10 @@ interface ConditionParserOptions {
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `defaultOperator` | `string` | `"eq"` | Default operator when not explicitly specified |
+| `defaultOperator` | `string` | `"eq"` | Default operator when not explicitly specified. Empty strings are ignored (fall back to the static default). |
 | `debug` | `boolean` | `false` | Enable debug logging to console |
 | `transform` | `function` | identity | Transform function applied to each parsed expression |
-| `preAddHook` | `function` | - | Hook called before adding each expression; return falsy to skip |
+| `preAddHook` | `function` | - | Hook called before adding each expression; return `null` / `undefined` to **drop** the expression (see notes below) |
 
 **Transform Example:**
 
@@ -174,11 +180,19 @@ const result = ConditionParser.parse("foo:bar baz:bat", {
   preAddHook: (ctx) => {
     if (ctx.key === "foo") return ctx; // include in parsed
     otherConditions.push(ctx); // route elsewhere
-    return null; // skip in parsed
+    return null; // drop from parsed
   }
 });
 ```
 
+**Drop semantics**:
+
+- The expression is omitted from `parsed` and from `meta`.
+- The "join to next sibling" operator attached to the dropped expression is **transferred to its predecessor** so the remaining chain reflects the original logical intent. For `a:1 and b:2 or c:3`, dropping `b:2` yields `a:1 or c:3` (the `or` that would have connected `b → c` is promoted).
+- If a parenthesized group ends up empty (every inner expression dropped), the group wrapper is removed from its parent automatically.
+
+> **Breaking change (1.8.0)**: previously, returning falsy from `preAddHook` silently substituted a `{key: "1", operator: <defaultOperator>, value: "1"}` placeholder (`1=1`) rather than dropping. If you relied on the placeholder, return it yourself from the hook.
+
 ---
 
 ### ConditionParserResult
@@ -190,14 +204,18 @@ interface ConditionParserResult {
   parsed: ConditionDump;
   unparsed: string;
   meta: Meta;
+  errors: ParseError[];
 }
 ```
 
 | Property | Type | Description |
 |----------|------|-------------|
 | `parsed` | `ConditionDump` | Array of parsed condition expressions (compatible with `@marianmeres/condition-builder`) |
-| `unparsed` | `string` | Any trailing text that couldn't be parsed (useful for free-text search) |
+| `unparsed` | `string` | Any free-text fragments that couldn't be parsed — both leading (before the first expression) and trailing (after the last parseable token), combined with a single space (useful for free-text search) |
 | `meta` | [`Meta`](#meta) | Metadata about the parsed expressions |
+| `errors` | [`ParseError[]`](#parseerror) | Diagnostic records for any syntactic issues encountered; empty on clean parse |
+
+> For **strict validation** (distinguish "syntax error" from "trailing free text"), check both `errors.length === 0` **and** `unparsed === ""`.
 
 ---
 
@@ -209,7 +227,7 @@ Metadata about the parsed expressions.
 interface Meta {
   keys: string[];
   operators: string[];
-  values: any[];
+  values: string[];
   expressions: ExpressionData[];
 }
 ```
@@ -218,9 +236,11 @@ interface Meta {
 |----------|------|-------------|
 | `keys` | `string[]` | Array of unique keys found in parsed expressions |
 | `operators` | `string[]` | Array of unique operators found in parsed expressions |
-| `values` | `any[]` | Array of unique values found in parsed expressions |
+| `values` | `string[]` | Array of unique values found in parsed expressions (string-equality deduplicated) |
 | `expressions` | [`ExpressionData[]`](#expressiondata) | Array of unique expressions as objects |
 
+> **Type narrowing (1.8.0)**: `values` is now typed `string[]` (was `any[]`). Runtime behavior is unchanged — parser output has always been strings — but strict `any[]` consumers may need to update their type annotations.
+
 **Example:**
 
 ```ts
@@ -258,6 +278,28 @@ interface ExpressionData {
 
 ---
 
+### ParseError
+
+Diagnostic record describing where/why parsing stopped short.
+
+```ts
+interface ParseError {
+  message: string;
+  position: number;
+  snippet: string;
+}
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `message` | `string` | Human-readable error message (e.g. `"Unterminated quoted string"`) |
+| `position` | `number` | Zero-based index in the original input where the error was detected |
+| `snippet` | `string` | Short slice of the input surrounding `position` (context window) |
+
+A non-empty `errors` array **does not** imply `parsed` is empty — any successfully parsed prefix is preserved and the failing token(s) are rolled into `unparsed`.
+
+---
+
 ## Expression Syntax
 
 ### Basic Expressions
@@ -279,12 +321,22 @@ Use single or double quotes for identifiers containing spaces or special charact
 
 ### Escaped Characters
 
-Escape special characters with backslash:
+Backslash-escape special characters. Stray backslashes (not followed by an escapable char) are kept literally.
+
+| Context | Escapable chars |
+|---------|-----------------|
+| Quoted strings (`"..."` / `'...'`) | `\\`, matching quote (`\"` or `\'`) |
+| Parenthesized values (`(...)`) | `\\`, `\(`, `\)` |
+| Unquoted tokens | `\\`, `\:`, `\(`, `\)`, `\ ` (space), `\⇥` (tab) |
+
+Examples:
 
 ```
 "value with \" quote"    -> value with " quote
 'value with \' quote'    -> value with ' quote
-key\:colon:value         -> key: "key:colon"
+"path\\to\\file"         -> path\to\file
+key\:colon:value         -> { key: "key:colon", value: "value" }
+key:(value with \) paren) -> value: "value with ) paren"
 ```
 
 ### Parenthesized Values
@@ -294,9 +346,12 @@ Wrap values in parentheses (useful for complex values):
 ```
 key:(value with spaces)
 key:eq:(complex value)
+key:eq:(a(b)c)           -> value: "a(b)c"   (balanced nested parens)
 key:eq:(value with \) paren)
 ```
 
+> **Nested parens (1.8.0)**: parenthesized values now preserve balanced nested `()` as literal content. Previously the first unescaped `)` terminated the value.
+
 ### Logical Operators
 
 ```
@@ -318,14 +373,30 @@ a:b and (c:d or (e:f and g:h))
 
 ### Free Text
 
-Any trailing unparsable content is preserved:
+Unparsable content surrounding a contiguous parseable middle is preserved.
+Both **leading** (before the first expression) and **trailing** (after the
+last parseable token) fragments are collected into `unparsed`, single-space
+joined:
 
 ```
 category:books the search query
 // parsed: category:books
 // unparsed: "the search query"
+
+the search query category:books
+// parsed: category:books
+// unparsed: "the search query"
+
+the search category:books query
+// parsed: category:books
+// unparsed: "the search query"
 ```
 
+> **Limitation**: only free text that wraps a *contiguous* parseable section
+> is reassembled. Free text appearing **between** two expressions (e.g.,
+> `a:b free c:d`) breaks the parse at the interstitial token, so `c:d`
+> ends up inside `unparsed` along with `"free"`.
+
 ---
 
 ## Integration with condition-builder
@@ -353,3 +424,19 @@ c.and("user_id", "eq", 123).and(
 console.log(c.toString());
 // "user_id"='123' and (("folder"='my projects' or "folder"='inbox') and "text"~*'foo bar')
 ```
+
+---
+
+## Breaking Changes
+
+### 1.8.0
+
+1. **`preAddHook` falsy return now drops the expression** (previously replaced with a `{key: "1", operator: defaultOperator, value: "1"}` placeholder). The dropped expression's "join to next" operator is transferred to its predecessor, and empty parenthesized groups collapse. See [PreAddHook Example](#preaddhook-example). *Migration*: if you relied on the `1=1` placeholder, return it explicitly from your hook.
+2. **`ConditionParserResult.errors: ParseError[]`** is a new required field on the result. *Migration*: consumers using the destructured shape `{ parsed, unparsed, meta }` are unaffected; code constructing `ConditionParserResult` literals needs to add `errors: []`.
+3. **`Meta.values` is now typed `string[]`** (was `any[]`). Runtime behavior unchanged. *Migration*: update strict type annotations if needed.
+4. **Parser no longer throws a bogus "Parentheses level mismatch"** for balanced inputs starting with one or more `(`. Previously the throw was silently swallowed — the visible effect is that `errors` no longer holds a phantom entry for inputs like `((foo:bar))`.
+5. **Stray `not` in trailing terms is no longer consumed.** `a:b and c:d not e:f` now preserves `c:d` (previously dropped) and routes `not e:f` to `unparsed`. The `not` keyword is still recognized when it sits immediately after an `and` / `or` join.
+6. **Backslash escapes apply to backslash itself.** `"foo\\bar"` now yields `foo\bar`; previously the input was unterminated. Also applies to parenthesized values.
+7. **Parenthesized values support balanced nested parens.** `key:(a(b)c)` now yields `a(b)c`; previously the first `)` terminated the value.
+8. **Unquoted tokens can escape more characters**: `\\`, `\:`, `\(`, `\)`, `\ ` (space), `\⇥` (tab). Previously only `\:` was recognized.
+9. **Empty `defaultOperator` option silently falls back** to `ConditionParser.DEFAULT_OPERATOR` (`"eq"` by default). Previously could produce malformed expressions.

package/CLAUDE.md

@@ -0,0 +1,51 @@
+# @marianmeres/condition-parser
+
+Human-friendly search conditions parser (Gmail-style syntax) for Deno/Node.js.
+
+## Quick Facts
+
+- **Entry**: `src/mod.ts` -> `src/parser.ts`
+- **Main API**: `ConditionParser.parse(input, options?)` returns `{ parsed, unparsed, meta }`
+- **Tests**: `deno task test` (30 tests)
+- **Integrates with**: `@marianmeres/condition-builder`
+
+## Syntax
+
+```
+key:value               # implicit "eq" operator
+key:operator:value      # explicit operator
+"key":"op":"value"      # quoted (spaces allowed)
+a:b and c:d             # AND join
+a:b or c:d              # OR join
+a:b and not c:d         # AND NOT
+(a:b or c:d) and e:f    # grouping
+category:books query    # trailing text -> unparsed
+```
+
+## Options
+
+```typescript
+{
+  defaultOperator: "eq",  // operator when not specified
+  debug: false,           // console logging
+  transform: (ctx) => ctx,    // modify expressions
+  preAddHook: (ctx) => ctx    // filter expressions (return null to skip)
+}
+```
+
+## Result
+
+```typescript
+{
+  parsed: ConditionDump,  // structured conditions
+  unparsed: string,       // trailing free text
+  meta: { keys, operators, values, expressions }
+}
+```
+
+## Files
+
+- `src/parser.ts` - Parser implementation (recursive descent)
+- `tests/all.test.ts` - Test suite
+- `API.md` - Full API documentation
+- `AGENTS.md` - Machine-friendly docs

package/README.md

@@ -65,11 +65,13 @@ You can use escaped quotes (or colons) inside the identifiers:
 `"my key":'my \: operator':"my \" value with quotes" and (foo:<:bar or baz:>:bat)`
 ```
 
-Also, you can append arbitrary unparsable content which will be preserved:
+Also, you can mix in arbitrary unparsable content — around a contiguous
+parseable middle — which will be preserved. Both leading and trailing
+free-text fragments are collected into `unparsed` (single-space joined):
 
 ```ts
 const result = ConditionParser.parse(
-    "a:b and (c:d or e:f) this is free text", 
+    "this is a:b and (c:d or e:f) free text",
     options: Partial<ConditionParserOptions> // read below
 );
 
@@ -88,17 +90,25 @@ const result = ConditionParser.parse(
             operator: "and"
         }
     ],
-    unparsed: "this is free text"
+    unparsed: "this is free text",
+    meta:   { /* unique keys/operators/values/expressions */ },
+    errors: []   // non-empty on syntactic problems; see API.md
 }
 
 // ConditionParser.parse options (all optional):
 // - defaultOperator: string (default "eq") - operator when not specified
 // - debug: boolean (default false) - enable debug logging
 // - transform: (ctx) => ctx - transform each parsed expression
-// - preAddHook: (ctx) => ctx|null - filter/route expressions before adding
+// - preAddHook: (ctx) => ctx|null|undefined - return falsy to DROP the expression
 ```
 
-See [API.md](./API.md) for complete API documentation.
+For strict validation (e.g. form input), check both:
+
+```ts
+const ok = errors.length === 0 && unparsed.trim() === "";
+```
+
+See [API.md](./API.md) for complete API documentation, including the [Breaking Changes](./API.md#breaking-changes) section for 1.8.0.
 
 ## In friends harmony with condition-builder
 

package/dist/parser.d.ts

@@ -21,10 +21,25 @@ export interface Meta {
     /** Array of unique operators found in the parsed expressions */
     operators: string[];
     /** Array of unique values found in the parsed expressions */
-    values: any[];
+    values: string[];
     /** Array of unique expressions as {key, operator, value} objects */
     expressions: ExpressionData[];
 }
+/**
+ * A diagnostic record produced when the parser cannot fully consume the input.
+ *
+ * The parser remains permissive (errors are not thrown to the caller) but they
+ * are surfaced here so consumers like validators can distinguish between
+ * "trailing free text" and "syntax error mid-expression".
+ */
+export interface ParseError {
+    /** Human-readable error message. */
+    message: string;
+    /** Zero-based character position in the original input where the error was detected. */
+    position: number;
+    /** A short slice of the input around `position` (with surrounding context). */
+    snippet: string;
+}
 /**
  * Result returned by {@link ConditionParser.parse}.
  */
@@ -43,6 +58,14 @@ export interface ConditionParserResult {
      * Metadata about the parsed expressions (unique keys, operators, values).
      */
     meta: Meta;
+    /**
+     * Diagnostic errors collected while parsing. Empty when the input parsed cleanly.
+     *
+     * Note: a non-empty `errors` does not necessarily mean `parsed` is empty —
+     * any successfully parsed prefix is preserved. Consumers wanting strict
+     * validation should check both `errors.length === 0` and `unparsed === ""`.
+     */
+    errors: ParseError[];
 }
 /**
  * Configuration options for the ConditionParser.
@@ -76,10 +99,22 @@ export interface ConditionParserOptions {
     transform: (context: ExpressionContext) => ExpressionContext;
     /**
      * Hook function called before adding each expression to the output.
-     * If it returns a falsy value, the expression will be skipped.
-     * Useful for filtering or routing expressions to different destinations.
+     *
+     * Return the (possibly modified) `ExpressionContext` to keep the expression,
+     * or return `null` / `undefined` to **drop** it from the output.
+     *
+     * When an expression is dropped:
+     * - The expression is omitted from `parsed` and from `meta`.
+     * - The "join to next sibling" operator that was attached to the dropped
+     *   expression is transferred to its predecessor (if any), so the remaining
+     *   chain reflects the user's original logical intent as closely as possible.
+     * - If a parenthesized group ends up with no expressions, the group itself
+     *   is removed from its parent.
+     *
+     * Useful for filtering or routing expressions to a different sink.
+     *
      * @param context - The parsed expression context
-     * @returns The expression context to add, or null/undefined to skip
+     * @returns The expression context to add, or `null` / `undefined` to skip
      * @example
      * ```ts
      * preAddHook: (ctx) => {
@@ -129,11 +164,21 @@ export declare class ConditionParser {
     #private;
     /**
      * Default operator used when none is specified in the expression.
+     *
+     * Note: this is a writable static for convenience, but mutating it affects
+     * every subsequent `ConditionParser.parse` call in the process. Prefer the
+     * per-call `defaultOperator` option in long-lived processes.
+     *
      * @default "eq"
      */
     static DEFAULT_OPERATOR: string;
     /**
      * Global debug flag. When true, all parser instances will log debug information.
+     *
+     * Note: this is a writable static for convenience, but mutating it affects
+     * every subsequent `ConditionParser.parse` call in the process. Prefer the
+     * per-call `debug` option in long-lived processes.
+     *
      * @default false
      */
     static DEBUG: boolean;
@@ -172,6 +217,7 @@ export declare class ConditionParser {
      *   - `parsed`: Array of parsed condition expressions in ConditionDump format
      *   - `unparsed`: Any trailing text that couldn't be parsed (useful for free-text search)
      *   - `meta`: Metadata about the parsed expressions (unique keys, operators, values)
+     *   - `errors`: Diagnostic records collected during parsing (empty when successful)
      *
      * @example
      * Basic parsing:

package/dist/parser.js

@@ -1,3 +1,8 @@
+/**
+ * Sentinel pushed in place of an item that was skipped by `preAddHook`.
+ * It is removed from `out` after `parseTerm` returns; consumers never see it.
+ */
+const SKIP_MARKER = Symbol("ConditionParser.skip");
 /**
  * Human-friendly conditions notation parser for search expressions.
  *
@@ -36,11 +41,21 @@
 export class ConditionParser {
     /**
      * Default operator used when none is specified in the expression.
+     *
+     * Note: this is a writable static for convenience, but mutating it affects
+     * every subsequent `ConditionParser.parse` call in the process. Prefer the
+     * per-call `defaultOperator` option in long-lived processes.
+     *
      * @default "eq"
      */
     static DEFAULT_OPERATOR = "eq";
     /**
      * Global debug flag. When true, all parser instances will log debug information.
+     *
+     * Note: this is a writable static for convenience, but mutating it affects
+     * every subsequent `ConditionParser.parse` call in the process. Prefer the
+     * per-call `debug` option in long-lived processes.
+     *
      * @default false
      */
     static DEBUG = false;
@@ -51,21 +66,22 @@ export class ConditionParser {
     #debugEnabled = false;
     #depth = -1;
     #meta = {
-        keys: new Set([]),
-        operators: new Set([]),
-        values: new Set([]),
-        expressions: new Set([]),
+        keys: new Set(),
+        operators: new Set(),
+        values: new Set(),
+        expressions: new Set(),
     };
     #transform;
     #preAddHook;
     constructor(input, options = {}) {
         input = `${input}`.trim();
-        // removing this... makes no sense
-        // if (!input) throw new TypeError(`Expecting non empty input`);
         const { defaultOperator = ConditionParser.DEFAULT_OPERATOR, debug = false, transform = (c) => c, preAddHook, } = options ?? {};
         this.#input = input;
         this.#length = input.length;
-        this.#defaultOperator = defaultOperator;
+        this.#defaultOperator =
+            typeof defaultOperator === "string" && defaultOperator
+                ? defaultOperator
+                : ConditionParser.DEFAULT_OPERATOR;
         this.#debugEnabled = !!debug;
         this.#debug(`[ ${this.#input} ]`, this.#defaultOperator);
         this.#transform = transform;
@@ -129,7 +145,7 @@ export class ConditionParser {
     /** Will look ahead (if positive) or behind (if negative) based on `offset` */
     #peek(offset = 0) {
         const at = this.#pos + offset;
-        return at < this.#length ? this.#input[at] : "";
+        return at >= 0 && at < this.#length ? this.#input[at] : "";
     }
     /** Will move the internal cursor one character ahead */
     #consume() {
@@ -138,7 +154,7 @@ export class ConditionParser {
     /** Will move the internal cursor at the end of the currently ahead whitespace block. */
     #consumeWhitespace() {
         while (this.#pos < this.#length && /\s/.test(this.#peek())) {
-            this.#consume();
+            this.#pos++;
         }
     }
     /** Will look ahead to see if there is a single or double quote */
@@ -152,6 +168,13 @@ export class ConditionParser {
     #isEOF() {
         return this.#pos >= this.#length;
     }
+    /**
+     * Reads a parenthesized value: `(...)`. Supports balanced nested parens
+     * and backslash escapes for `\(`, `\)`, and `\\`.
+     *
+     * The opening `(` is consumed; the matching closing `)` is consumed too.
+     * The returned string contains everything in between (with escapes resolved).
+     */
     #parseParenthesizedValue() {
         this.#debug("parseParenthesizedValue:start");
         // sanity
@@ -161,109 +184,161 @@ export class ConditionParser {
         // Consume opening (
         this.#consume();
         let result = "";
-        const closing = ")";
+        let depth = 1;
         while (this.#pos < this.#length) {
             const char = this.#consume();
-            if (char === closing && this.#peek(-2) !== "\\") {
-                this.#debug("parseParenthesizedValue:result", result, this.#peek());
-                return result;
+            if (char === "\\") {
+                const next = this.#peek();
+                if (next === "(" || next === ")" || next === "\\") {
+                    result += next;
+                    this.#consume();
+                    continue;
+                }
+                // Stray backslash — keep literal.
+                result += char;
+                continue;
             }
-            if (char === "\\" && this.#peek() === closing) {
-                result += closing;
-                this.#consume(); // Skip the escaped char
+            if (char === "(") {
+                depth++;
+                result += char;
+                continue;
             }
-            else {
+            if (char === ")") {
+                depth--;
+                if (depth === 0) {
+                    this.#debug("parseParenthesizedValue:result", result, this.#peek());
+                    return result;
+                }
                 result += char;
+                continue;
             }
+            result += char;
         }
         throw this.#createError("Unterminated parenthesized string");
     }
-    /** Will parse the currently ahead quoted block with escape support.
-     * Supports both single ' and double " quotes. */
+    /**
+     * Reads a single- or double-quoted string with backslash escapes.
+     * Supports `\\` (literal backslash), `\<quote>` (literal quote of the
+     * matching kind), plus stray backslashes are kept literal.
+     */
     #parseQuotedString() {
         this.#debug("parseQuotedString:start");
         // sanity
         if (!this.#isQuoteAhead()) {
             throw this.#createError("Not quoted string");
         }
-        let result = "";
         // Consume opening quote
         const quote = this.#consume();
+        let result = "";
         while (this.#pos < this.#length) {
             const char = this.#consume();
-            if (char === quote && this.#peek(-2) !== "\\") {
+            if (char === "\\") {
+                const next = this.#peek();
+                if (next === quote || next === "\\") {
+                    result += next;
+                    this.#consume();
+                    continue;
+                }
+                // Stray backslash — keep literal.
+                result += char;
+                continue;
+            }
+            if (char === quote) {
                 this.#debug("parseQuotedString:result", result);
                 return result;
             }
-            if (char === "\\" && this.#peek() === quote) {
-                result += quote;
-                this.#consume(); // Skip the escaped quote
-            }
-            else {
-                result += char;
-            }
+            result += char;
         }
         throw this.#createError("Unterminated quoted string");
     }
-    /** Will parse the currently ahead unquoted block until delimiter ":", "(", ")", or \s) */
+    /**
+     * Reads an unquoted token, terminated by `:`, `(`, `)`, or whitespace.
+     * Backslash escapes for `\:`, `\\`, `\ ` (space), `\(`, `\)` are supported;
+     * stray backslashes are kept literal.
+     */
     #parseUnquotedString() {
         this.#debug("parseUnquotedString:start");
         let result = "";
         while (this.#pos < this.#length) {
             const char = this.#peek();
-            if ((char === ":" && this.#peek(-1) !== "\\") ||
+            if (char === "\\") {
+                const next = this.#peek(1);
+                if (next === ":" ||
+                    next === "\\" ||
+                    next === "(" ||
+                    next === ")" ||
+                    next === " " ||
+                    next === "\t") {
+                    result += next;
+                    this.#consume(); // backslash
+                    this.#consume(); // escaped char
+                    continue;
+                }
+                // Stray backslash — keep literal and continue.
+                result += this.#consume();
+                continue;
+            }
+            if (char === ":" ||
                 char === "(" ||
                 char === ")" ||
                 /\s/.test(char)) {
                 break;
             }
-            if (char === "\\" && this.#peek(1) === ":") {
-                result += ":";
-                this.#consume(); // Skip the backslash
-                this.#consume(); // Skip the escaped colon
-            }
-            else {
-                result += this.#consume();
-            }
+            result += this.#consume();
         }
         result = result.trim();
         this.#debug("parseUnquotedString:result", result);
         return result;
     }
-    /** Will parse the "and" or "or" logical operator */
-    #parseConditionOperator(openingParenthesesLevel) {
+    /**
+     * Tries to parse an `and` / `or` / `and not` / `or not` join operator at
+     * the current position. Returns the matched operator or `null` if none.
+     *
+     * The "not" suffix is only matched when it appears **immediately** after
+     * the join keyword (separated by whitespace), preventing earlier bugs
+     * where `not` anywhere later in the input could capture the cursor.
+     */
+    #parseConditionOperator() {
         this.#debug("parseConditionOperator:start", this.#peek());
         this.#consumeWhitespace();
         const remaining = this.#input.slice(this.#pos);
         let result = null;
-        const _isNotAhead = (s) => /\s*not\s+/i.exec(s);
-        if (/^and /i.test(remaining)) {
-            this.#pos += 4;
+        // Match a "not " (or "not" at EOF would be bogus — require trailing ws).
+        const notAfter = (afterIndex) => {
+            const slice = remaining.slice(afterIndex);
+            const m = /^\s*not(\s+|$)/i.exec(slice);
+            return m ? m[0].length : 0;
+        };
+        if (/^and(\s|$)/i.test(remaining)) {
+            this.#pos += 3;
             result = "and";
-            // maybe followed by "not"?
-            const notIsAheadMatch = _isNotAhead(remaining);
-            if (notIsAheadMatch) {
-                // minus 1, because the initial test includes single trailing whitespace
-                this.#pos += notIsAheadMatch[0].length - 1;
+            const skip = notAfter(3);
+            // only treat as "and not" if there is something AFTER the "not " too
+            if (skip && remaining.length > 3 + skip) {
+                this.#pos += skip;
                 result = "andNot";
             }
+            else if (!skip) {
+                // require at least one whitespace after "and"
+                if (!/^and\s/i.test(remaining)) {
+                    this.#pos -= 3;
+                    result = null;
+                }
+            }
         }
-        else if (/^or /i.test(remaining)) {
-            this.#pos += 3;
+        else if (/^or(\s|$)/i.test(remaining)) {
+            this.#pos += 2;
             result = "or";
-            // maybe followed by "not"?
-            const notIsAheadMatch = _isNotAhead(remaining);
-            if (notIsAheadMatch) {
-                // minus 1, because the initial test includes single trailing whitespace
-                this.#pos += notIsAheadMatch[0].length - 1;
+            const skip = notAfter(2);
+            if (skip && remaining.length > 2 + skip) {
+                this.#pos += skip;
                 result = "orNot";
             }
-        }
-        else if (openingParenthesesLevel !== undefined) {
-            const preLevel = openingParenthesesLevel;
-            const postLevel = this.#countSameCharsAhead(")");
-            if (preLevel !== postLevel) {
-                throw this.#createError(`Parentheses level mismatch (opening: ${preLevel}, closing: ${postLevel})`);
+            else if (!skip) {
+                if (!/^or\s/i.test(remaining)) {
+                    this.#pos -= 2;
+                    result = null;
+                }
             }
         }
         this.#debug("parseConditionOperator:result", result);
@@ -272,51 +347,33 @@ export class ConditionParser {
     /** Will parse the key:operator:value segment */
     #parseBasicExpression(out, currentOperator) {
         this.#debug("parseBasicExpression:start", currentOperator);
-        // so we can restore "unparsed"
+        // so we can restore "unparsed" — any error that escapes this method
+        // rewinds the cursor to the start of the token, so the caller surfaces
+        // the whole bad expression as `unparsed` (rather than a silently-eaten
+        // slice of it).
         const _startPos = this.#pos;
         let key;
-        if (this.#isQuoteAhead()) {
-            key = this.#parseQuotedString();
-        }
-        else {
-            key = this.#parseUnquotedString();
-        }
-        // Consume the first colon
-        this.#consumeWhitespace();
-        if (this.#consume() !== ":") {
-            this.#pos = _startPos;
-            throw this.#createError("Expected colon after key");
-        }
-        this.#consumeWhitespace();
-        // Check if we have an operator
-        let operator = this.#defaultOperator;
+        let operator;
         let value;
         let wasParenthesized = false;
-        // Try to parse as if we have an operator
-        if (this.#isOpeningParenthesisAhead()) {
-            wasParenthesized = true;
-            value = this.#parseParenthesizedValue();
-        }
-        else if (this.#isQuoteAhead()) {
-            value = this.#parseQuotedString();
-        }
-        else {
-            value = this.#parseUnquotedString();
-        }
-        this.#consumeWhitespace();
-        // If we find a colon, what we parsed was actually an operator
-        if (this.#peek() === ":") {
-            if (wasParenthesized) {
-                this.#pos = _startPos;
-                throw this.#createError("Operator cannot be a parenthesized expression");
+        try {
+            if (this.#isQuoteAhead()) {
+                key = this.#parseQuotedString();
+            }
+            else {
+                key = this.#parseUnquotedString();
+            }
+            // Consume the first colon
+            this.#consumeWhitespace();
+            if (this.#consume() !== ":") {
+                throw this.#createError("Expected colon after key");
             }
-            operator = value;
-            this.#consume(); // consume the second colon
             this.#consumeWhitespace();
-            // Parse the actual value
+            // Check if we have an operator
+            operator = this.#defaultOperator;
+            // Try to parse as if we have an operator
             if (this.#isOpeningParenthesisAhead()) {
-                // this.#pos = _startPos;
-                // throw new Error("Value cannot be a parenthesized expression");
+                wasParenthesized = true;
                 value = this.#parseParenthesizedValue();
             }
             else if (this.#isQuoteAhead()) {
@@ -325,23 +382,53 @@ export class ConditionParser {
             else {
                 value = this.#parseUnquotedString();
             }
+            this.#consumeWhitespace();
+            // If we find a colon, what we parsed was actually an operator
+            if (this.#peek() === ":") {
+                if (wasParenthesized) {
+                    throw this.#createError("Operator cannot be a parenthesized expression");
+                }
+                operator = value;
+                this.#consume(); // consume the second colon
+                this.#consumeWhitespace();
+                // Parse the actual value
+                if (this.#isOpeningParenthesisAhead()) {
+                    value = this.#parseParenthesizedValue();
+                }
+                else if (this.#isQuoteAhead()) {
+                    value = this.#parseQuotedString();
+                }
+                else {
+                    value = this.#parseUnquotedString();
+                }
+            }
         }
-        let expression = this.#transform?.({
-            key,
-            operator,
-            value,
-        }) ?? {
-            key,
-            operator,
-            value,
-        };
-        if (typeof this.#preAddHook === "function") {
-            expression = this.#preAddHook(expression);
-            // return early if hook returned falsey
-            if (!expression) {
-                this.#debug("parseBasicExpression:preAddHook truthy skip...");
-                expression = { key: "1", operator: this.#defaultOperator, value: "1" };
+        catch (e) {
+            this.#pos = _startPos;
+            throw e;
+        }
+        // Apply transform; we trust the user's transform to return a context.
+        const transformed = this.#transform({ key, operator, value });
+        const expression = transformed ?? { key, operator, value };
+        // preAddHook may drop the expression entirely.
+        if (this.#preAddHook) {
+            const kept = this.#preAddHook(expression);
+            if (!kept) {
+                this.#debug("parseBasicExpression:preAddHook drop");
+                // Push a skip marker; #parseCondition will remove it AFTER it has
+                // had a chance to set its operator from the next iteration's
+                // conditionOperator. This is essential to correctly transfer the
+                // "join to next" operator from the dropped item to its predecessor.
+                out.push({
+                    __skip: SKIP_MARKER,
+                    operator: currentOperator,
+                });
+                return;
             }
+            // preAddHook may have returned a modified context.
+            expression.key = kept.key;
+            expression.operator = kept.operator;
+            expression.value = kept.value;
         }
         const result = {
             expression,
@@ -349,9 +436,11 @@ export class ConditionParser {
             condition: undefined,
         };
         this.#debug("parseBasicExpression:result", result);
-        this.#meta.keys.add(expression.key);
-        this.#meta.operators.add(expression.operator);
-        this.#meta.values.add(expression.value);
+        this.#meta.keys.add(String(expression.key));
+        this.#meta.operators.add(String(expression.operator));
+        this.#meta.values.add(typeof expression.value === "string"
+            ? expression.value
+            : String(expression.value));
         // need to make it unique... so just quick-n-dirty
         this.#meta.expressions.add(JSON.stringify([expression.key, expression.operator, expression.value]));
         out.push(result);
@@ -365,12 +454,13 @@ export class ConditionParser {
         this.#consume();
         this.#consumeWhitespace();
         // IMPORTANT: we're going deeper, so need to create the nested level
+        const nested = [];
         out.push({
-            condition: [],
+            condition: nested,
             operator: currentOperator,
             expression: undefined,
         });
-        this.#parseCondition(out.at(-1).condition, currentOperator);
+        this.#parseCondition(nested, currentOperator);
         this.#consumeWhitespace();
         if (this.#peek() !== ")") {
             this.#pos = _startPos;
@@ -378,6 +468,11 @@ export class ConditionParser {
         }
         // consume closing parenthesis
         this.#consume();
+        // If the inner condition ended up empty (e.g. all members were dropped
+        // by preAddHook), drop the wrapper too.
+        if (nested.length === 0) {
+            out.pop();
+        }
         this.#debug("parseParenthesizedExpression:result");
     }
     /** Will parse either basic or parenthesized term based on look ahead */
@@ -393,42 +488,29 @@ export class ConditionParser {
         }
         this.#debug("parseTerm:end", this.#peek());
     }
-    /** will count how many same exact consequent `char`s are ahead (excluding whitespace) */
-    #countSameCharsAhead(char) {
-        const posBkp = this.#pos;
-        let count = 0;
-        let next = this.#consume();
-        while (next === char) {
-            count++;
-            this.#consumeWhitespace();
-            next = this.#consume();
-        }
-        this.#pos = posBkp;
-        return count;
-    }
-    #moveToFirstMatch(regex) {
-        let bkp = this.#pos;
-        let next = this.#consume();
-        let match = next && regex.test(next);
-        while (match) {
-            this.#consumeWhitespace();
-            bkp = this.#pos;
-            next = this.#consume();
-            match = next && regex.test(next);
-        }
-        this.#pos = bkp;
+    /**
+     * Test whether the last entry in `out` is a skip marker (placeholder that
+     * will not survive into the public output).
+     */
+    #lastIsSkip(out) {
+        const last = out.at(-1);
+        return !!last && last.__skip === SKIP_MARKER;
     }
     /** Parses sequences of terms connected by logical operators (and/or) */
-    #parseCondition(out, conditionOperator, openingParenthesesLevel) {
+    #parseCondition(out, conditionOperator) {
         this.#depth++;
         this.#consumeWhitespace();
         this.#debug("parseCondition:start", conditionOperator, this.#peek());
         // Parse first term
         this.#parseTerm(out, conditionOperator);
+        // If the very first term was a skip placeholder, remove it before the
+        // loop runs — it has no predecessor to inherit its operator.
+        if (this.#lastIsSkip(out))
+            out.pop();
         // Parse subsequent terms
         while (true) {
             this.#consumeWhitespace();
-            conditionOperator = this.#parseConditionOperator(openingParenthesesLevel);
+            conditionOperator = this.#parseConditionOperator();
             // no recognized condition
             if (!conditionOperator) {
                 this.#consumeWhitespace();
@@ -440,26 +522,109 @@ export class ConditionParser {
                     break;
                 }
             }
-            // point here is that we must expect #parseTerm below to fail (trailing
-            // unparsable content is legit), so we need to save current operator to
-            // be able to restore it
-            const _previousBkp = out.at(-1).operator;
-            // "previous" operator edit to match condition-builder convention
-            out.at(-1).operator = conditionOperator;
+            // "previous" operator edit to match condition-builder convention.
+            // If the previous slot is empty (very first term was skipped) skip
+            // the assignment — otherwise we set/transfer the operator.
+            const prev = out.at(-1);
+            const _previousBkp = prev?.operator;
+            if (prev)
+                prev.operator = conditionOperator;
             try {
                 this.#parseTerm(out, conditionOperator);
             }
             catch (e) {
                 this.#debug(`${e}`);
-                // restore
-                out.at(-1).operator = _previousBkp;
-                // and catch unparsed below
+                // restore on error so the previous chain isn't corrupted
+                if (prev)
+                    prev.operator = _previousBkp;
                 throw e;
             }
+            // If parseTerm pushed a skip marker, the "join to next" operator
+            // it would have carried is preserved on the predecessor (whose
+            // .operator we just set above). Remove the marker now so the chain
+            // stays clean for the next iteration.
+            if (this.#lastIsSkip(out))
+                out.pop();
         }
         this.#depth--;
         return out;
     }
+    /**
+     * Scans the input for the first position that could begin a valid condition
+     * expression. Returns that position, or -1 if nothing expression-like exists.
+     *
+     * A candidate start is either:
+     *   - an opening parenthesis `(` (start of a group), or
+     *   - a word / quoted string followed by optional whitespace and `:`.
+     *
+     * Everything before the returned position is surfaced as leading free text
+     * in `unparsed` (combined with any trailing free text).
+     */
+    #findFirstExpressionStart() {
+        const input = this.#input;
+        const len = this.#length;
+        let i = 0;
+        let wordStart = -1;
+        while (i < len) {
+            const ch = input[i];
+            // Paren group is a valid top-level expression start.
+            if (ch === "(")
+                return i;
+            // Whitespace breaks word tracking.
+            if (/\s/.test(ch)) {
+                wordStart = -1;
+                i++;
+                continue;
+            }
+            // Quoted string: treat the whole run as one "word". If the next
+            // non-whitespace after the closing quote is `:`, it's a key.
+            if (ch === '"' || ch === "'") {
+                const ws = wordStart < 0 ? i : wordStart;
+                const quote = ch;
+                i++;
+                while (i < len && input[i] !== quote) {
+                    if (input[i] === "\\" && i + 1 < len)
+                        i += 2;
+                    else
+                        i++;
+                }
+                if (i < len)
+                    i++; // closing quote
+                let j = i;
+                while (j < len && /\s/.test(input[j]))
+                    j++;
+                if (input[j] === ":")
+                    return ws;
+                wordStart = -1;
+                continue;
+            }
+            // Backslash escape: both chars belong to the current word.
+            if (ch === "\\" && i + 1 < len) {
+                if (wordStart < 0)
+                    wordStart = i;
+                i += 2;
+                continue;
+            }
+            // Stray `)` can't start an expression.
+            if (ch === ")") {
+                wordStart = -1;
+                i++;
+                continue;
+            }
+            // A `:` following a word marks a key boundary.
+            if (ch === ":") {
+                if (wordStart >= 0)
+                    return wordStart;
+                i++;
+                continue;
+            }
+            // Regular word character.
+            if (wordStart < 0)
+                wordStart = i;
+            i++;
+        }
+        return -1;
+    }
     /**
      * Parses a human-friendly search condition string into a structured format.
      *
@@ -469,6 +634,7 @@ export class ConditionParser {
      *   - `parsed`: Array of parsed condition expressions in ConditionDump format
      *   - `unparsed`: Any trailing text that couldn't be parsed (useful for free-text search)
      *   - `meta`: Metadata about the parsed expressions (unique keys, operators, values)
+     *   - `errors`: Diagnostic records collected during parsing (empty when successful)
      *
      * @example
      * Basic parsing:
@@ -497,19 +663,55 @@ export class ConditionParser {
      */
     static parse(input, options = {}) {
         const parser = new ConditionParser(input, options);
-        let parsed = [];
+        const internal = [];
         let unparsed = "";
-        const openingLevel = parser.#countSameCharsAhead("(");
-        try {
-            // Start with the highest-level logical expression
-            parsed = parser.#parseCondition(parsed, "and", openingLevel);
-        }
-        catch (_e) {
-            if (options.debug)
-                parser.#debug(`${_e}`);
-            // collect trailing unparsed input
-            unparsed = parser.#input.slice(parser.#pos);
+        const errors = [];
+        // Empty input is a no-op (avoid throwing "Expected colon after key" at pos 0).
+        if (parser.#length > 0) {
+            // Locate the first position that could start an expression; anything
+            // before it is "leading free text" which we surface as `unparsed`
+            // combined (space-joined) with any trailing free text.
+            const startPos = parser.#findFirstExpressionStart();
+            if (startPos < 0) {
+                // No expression-like start anywhere — whole input is free text.
+                unparsed = parser.#input;
+            }
+            else {
+                const leading = parser.#input.slice(0, startPos).trim();
+                parser.#pos = startPos;
+                try {
+                    parser.#parseCondition(internal, "and");
+                }
+                catch (e) {
+                    parser.#debug(`${e}`);
+                    // collect trailing unparsed input
+                    unparsed = parser.#input.slice(parser.#pos);
+                    const message = e instanceof Error ? e.message : String(e);
+                    // First line of `__createError`-formatted messages is the bare cause.
+                    const firstLine = message.split("\n", 1)[0];
+                    const start = Math.max(0, parser.#pos - 20);
+                    const end = Math.min(parser.#input.length, parser.#pos + 20);
+                    errors.push({
+                        message: firstLine,
+                        position: parser.#pos,
+                        snippet: parser.#input.slice(start, end),
+                    });
+                }
+                // Trailing content that wasn't grabbed by the throw path (e.g. an
+                // unmatched closing parenthesis at the top level breaks the parse
+                // loop without throwing). Surface it as `unparsed` to match the
+                // long-standing convention.
+                if (!unparsed && parser.#pos < parser.#length) {
+                    unparsed = parser.#input.slice(parser.#pos);
+                }
+                // Prepend any leading free text, single-space joined.
+                if (leading) {
+                    unparsed = unparsed ? `${leading} ${unparsed}` : leading;
+                }
+            }
         }
+        // Strip any lingering skip markers (defensive — should never happen).
+        const parsed = internal.filter((item) => !item || item.__skip !== SKIP_MARKER);
         return {
             parsed,
             unparsed,
@@ -522,6 +724,7 @@ export class ConditionParser {
                     return { key, operator, value };
                 }),
             },
+            errors,
         };
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/condition-parser",
-	"version": "1.7.4",
+	"version": "1.8.0",
 	"type": "module",
 	"main": "dist/mod.js",
 	"types": "dist/mod.d.ts",
@@ -10,10 +10,18 @@
 			"import": "./dist/mod.js"
 		}
 	},
+	"files": [
+		"dist",
+		"LICENSE",
+		"README.md",
+		"API.md",
+		"AGENTS.md",
+		"CLAUDE.md"
+	],
 	"author": "Marian Meres",
 	"license": "MIT",
 	"dependencies": {
-		"@marianmeres/condition-builder": "^1.9.3"
+		"@marianmeres/condition-builder": "^1.9.4"
 	},
 	"repository": {
 		"type": "git",