eval/typval: Add missing includes, also add a script to find them

Contains unfinished attempt to integrate IWYU (ref #549). To finish it different
job should be done, specifically:

- Instead of feeding IWYU with modified file a mirror source tree should be
  created with the help of CMake which will contain modified sources. This
  solves the problem with IWYU thinking that `*.generated.h` headers should be
  included in place of `*` headers.
- Build IWYU as all other third-party utilities.
- Make modified sources avoid problems with `nvim/func_attr.h` includes and
  various related tricks.

Current script may only be used for manual checks like this:

    ./scripts/check-includes.py \
        --generated-includes-dir build/include \
        --generated-includes-dir build/src/nvim/auto \
        --file src/nvim/eval/typval.c \
        -- -Isrc -Ibuild/include -Ibuild/src/nvim/auto \
           -DINCLUDE_GENERATED_DECLARATIONS

(it is also somewhat fine with `--file src/nvim/eval/typval.h`). I have no idea
why (I mean, why developer think that these lines are needed, why they are
suggested is pretty obvious: because there is typedef which mentions them before
structs are defined), but for typval.h it reports, among other things, that it
should add lines

    struct dictvar_S;
    struct listitem_S;
    struct listvar_S;
    struct listwatch_S;

1 files changed, 66 insertions, 0 deletions

diff --git a/scripts/check-includes.py b/scripts/check-includes.py
new file mode 100755
index 0000000000..21308a21aa
--- /dev/null
+++ b/scripts/check-includes.py
@@ -0,0 +1,66 @@
+#!/usr/bin/env python
+
+import sys
+import re
+import os
+
+from subprocess import Popen, PIPE
+from argparse import ArgumentParser
+
+
+GENERATED_INCLUDE_RE = re.compile(
+  r'^\s*#\s*include\s*"([/a-z_0-9.]+\.generated\.h)"(\s+//.*)?$')
+
+
+def main(argv):
+  argparser = ArgumentParser()
+  argparser.add_argument('--generated-includes-dir', action='append',
+                         help='Directory where generated includes are located.')
+  argparser.add_argument('--file', type=open, help='File to check.')
+  argparser.add_argument('iwyu_args', nargs='*',
+                         help='IWYU arguments, must go after --.')
+  args = argparser.parse_args(argv)
+
+  with args.file:
+    include_dirs = []
+
+    iwyu = Popen(['include-what-you-use', '-xc'] + args.iwyu_args + ['/dev/stdin'],
+                stdin=PIPE, stdout=PIPE, stderr=PIPE)
+
+    for line in args.file:
+      match = GENERATED_INCLUDE_RE.match(line)
+      if match:
+        for d in args.generated_includes_dir:
+          try:
+            f = open(os.path.join(d, match.group(1)))
+          except IOError:
+            continue
+          else:
+            with f:
+              for generated_line in f:
+                iwyu.stdin.write(generated_line)
+              break
+        else:
+          raise IOError('Failed to find {0}'.format(match.group(1)))
+      else:
+        iwyu.stdin.write(line)
+
+  iwyu.stdin.close()
+
+  out = iwyu.stdout.read()
+  err = iwyu.stderr.read()
+
+  ret = iwyu.wait()
+
+  if ret != 2:
+    print('IWYU failed with exit code {0}:'.format(ret))
+    print('{0} stdout {0}'.format('=' * ((80 - len(' stdout ')) // 2)))
+    print(out)
+    print('{0} stderr {0}'.format('=' * ((80 - len(' stderr ')) // 2)))
+    print(err)
+    return 1
+  return 0
+
+
+if __name__ == '__main__':
+  raise SystemExit(main(sys.argv[1:]))