Hey, thanks so much for the feedback! I started working on updating the docs and I'll try to address all these points. Just wanted to update the issue, as I couldn't push it today yet.

1 - the name of the file is neal.json, I'll push a commit with the fix for the readme soon, but in the meantime, there's more info about it here if you need.
2 & 3 - I'm finishing updating the docs soon.
4 - You got that working with vars + condition? Let me know if you want to share your rule and I can try to help.
5 - I'll see if I can add another "action", for debugging values of variables currently matched.
6 - Will add that to the docs. The way it works is it just access the property of the matched node. If it's an array, it basically does flatMap.
7 - Yeah, I messed that up when I was improving the performance of the swift parser, not a great tradeoff though :/ If you want to share the files that had syntax errors, I'm happy to debug and fix the parser. I'll also see what I can do about the errors, but that might take a bit longer.
8 - I'll try to explain that better in the docs, but the idea is that if it's a list, it'll execute the rule against each item in the list, i.e. list == "string" will be the same as there exists some x in list such that x == "string".
9 - Will update that! I have to fix it so that the code for printing it in failures can be shared with the core of the framework (which prints syntax errors for rules). Right now the build for NEAL is a bit sketchy, which makes it hard.
10 - You can set the NEAL_STATS=1 when running neal and it will print some info, e.g. the number of failures, warnings and parser failures. There's no number per rule unfortunate, but I can look into adding it. There's documentation about the runtime flags which can be set with environment variables here.

Thanks again for the feedback, I'll push a commit soon referencing this diff.

I was also looking for how to do cross tree sibling/cousin matches, and I think I now have something working, but there was a bunch of trial and error.

You got that working with vars + condition? Let me know if you want to share your rule and I can try to help.

I thought I had it working, but nope, it wasn't correct. tl;dr I was trying to identify nested closures that weakly captured self where the outer closure did not capture self weakly. I didn't describe it correctly, it's a ancestor/descendent relationship, not sibling/cousin. This is what led to the > operator, because I want to restrict the weak self check to a closure's direct child CaptureList, not those of nested closures.

Thanks for all the answers.

Here's one case where we see the SyntaxError when handling double optionals:

final class Foo {
    func bar(string: String??) {
        if case let string?? = string {}
    }
}

Here's another case:

final class Foo {
    func bar() {
        switch "" {
        case "foo":
            return
        default:
            break
        }
    }
}

Here's another case with multi-line strings:

final class Foo {
    func bar() {
        """
        Shouldn't be able to update a pickup location if there is no
        current ride, or the map isn't fully initialized
        """
    }
}

Another case with some weird characters for variable names:

final class Foo {
    func bar() {
        let sinφ = sin(0)
    }
}

Another case if you add a newline between your function name and the arguments 🙃

final class Foo {
    func bar
        (completion: @escaping () -> Void) {}
}

I think that's most of the case we have, happy to provide more info if that would be useful! This was with neal from homebrew with --HEAD at c40036d

Thanks for all the examples. Some of these issues are known: we have to add support for Swift 4 features (keypaths will also fail to parse) and there's no unicode support (OCaml doesn't like it). The issue with newlines is a bit more unfortunate indeed, but sadly Swift cares about newlines and (to the best of my knowledge) is not well documented where it's valid to have a newline or not, so it was implement based on trial and error (luckily I had a decent-sized codebase to test it). I'll get working on some of these errors, but let me know if you'd like to contribute :)

@keith all the parse errors you reported, except for unicode support, should be fixed on master. I still want to support unicode, but that's a slightly bigger task, so it might take a bit longer until I get to it. I'll try to publish a new version soon, but let me know if you try it out before.

@tadeuzagallo Is there syntax to express the "current node"? I'm finding myself wanting something like that for scoped matchers. For example, using . as "current node":

Node {
  . > Left {
    ...
  }

  . > Right {
    ...
  }
}

The following two don't have the same meaning.

One of Left and/or Right could be non-children descendants:

Node {
  Left {
    ...
  }
  Right {
    ...
  }
}

This guarantees individual parent/child relationship, but doesn't prevent the case where the Nodes are different instances.

Node > Left {
  ...
}
Node > Right {
  ...
}

@kastiglione Yeah, you're right, that's not supported but it does make a lot of sense. It should be easy to implement, I'll see if I can get this done soon.