[tests] Add explicit test for synthetic edges on directory tree nodes.

 - Also, add a doc note on this behavior.

Author: ddunbar

docs/buildsystem-internals.md

@@ -59,6 +59,12 @@ discovers, as follows:
      directory, but which **are** the output of some task. The client is
      currently responsible for ensuring that any commands which produce output
      in the directory should be strongly ordered before the signature node.
+
+     However, clients can explicitly make additional dependencies on the
+     directory tree by registering a phony command which produces the directory
+     used by the tree signature, and which adds input dependencies on other
+     nodes in the graph (for example, ones which may or may not produce content
+     within the directory tree, and thus must be run before it).
    ```
 
 3. Recursively request directory signatures for any directories discovered as

docs/buildsystem.rst

@@ -81,6 +81,14 @@ These are the supported node types:
     file on disk is changed. This is useful when the client cannot easily know
     in advance whether the node is expected to be a file or a directory, but
     should be treated as a directory tree if it is one.
+
+  The directory tree will eagerly scan the directory as soon as any commands
+  which produce the immediate directory are complete. This means that the build
+  graph **MUST** contain a complete dependency graph between the tree node and
+  any command which may produce content within the directory. If such a
+  dependency is missing, the build system will typically end up scanning the
+  directory before all content is produced, and this will result in the first
+  build being incomplete, and the next build redoing the remainder of the work.
 
 * Virtual Nodes: Nodes matching the name ``'<.*>'``, e.g. ``<gate-task>``, are
   *assumed* to be virtual nodes, and are used for adding arbitrary edges to the

tests/BuildSystem/Build/directory-tree-client-edges.llbuild

@@ -0,0 +1,33 @@
+# Check the ability of clients to add additional dependency on a directory tree.
+#
+
+# This is important because currently llbuild won't necessarily try to find any
+# unmodeled dependency edges between outputs which fill in contents of a
+# directory and the directory tree node itself. Currently, clients must supply
+# any missing unmodeled edges explicitly.
+#
+# RUN: rm -rf %t.build
+# RUN: mkdir -p %t.build
+# RUN: cp %s %t.build/build.llbuild
+# RUN: echo "file" > %t.build/file
+# RUN: %{llbuild} buildsystem build --serial --chdir %t.build > %t.initial.out
+# RUN: %{FileCheck} --check-prefix=CHECK-INITIAL --input-file=%t.initial.out %s
+#
+# CHECK-INITIAL: SUBDIR-CONTENTS
+
+client:
+  name: basic
+
+targets:
+  "": ["subdir/"]
+
+commands:
+  C.subdir-dependencies:
+    tool: phony
+    inputs: ["<subdir-contents>"]
+    outputs: ["subdir"]
+  C.subdir-contents:
+    tool: shell
+    description: SUBDIR-CONTENTS
+    outputs: ["<subdir-contents>"]
+    args: mkdir -p subdir && touch subdir/foo