Add file scoped extensible directives.

- Added `DirectiveUsage` to enable extensible directive authors to indicate how their directives should be used. Currently support `Unrestricted` (how section directives have always worked and a single pre-content based directive.
- Added directive parsing tests.
- Removed no longer used `BlockKindInternal` items.

#1376

src/Microsoft.AspNetCore.Razor.Language/DirectiveDescriptor.cs

@@ -38,6 +38,12 @@ public abstract class DirectiveDescriptor
         /// </summary>
         public abstract DirectiveKind Kind { get; }
 
+        /// <summary>
+        /// Gets the way a directive can be used. The usage determines how many directives can exist per document 
+        /// and where they can exist.
+        /// </summary>
+        public abstract DirectiveUsage Usage { get; }
+
         /// <summary>
         /// Gets the list of directive tokens that can follow the directive keyword.
         /// </summary>
@@ -189,6 +195,8 @@ public DefaultDirectiveDescriptorBuilder(string name, DirectiveKind kind)
 
             public DirectiveKind Kind { get; }
 
+            public DirectiveUsage Usage { get; set; }
+
             public IList<DirectiveTokenDescriptor> Tokens { get; }
 
             public DirectiveDescriptor Build()
@@ -218,7 +226,7 @@ public DirectiveDescriptor Build()
                     }
                 }
 
-                return new DefaultDirectiveDescriptor(Directive, Kind, Tokens.ToArray(), DisplayName, Description);
+                return new DefaultDirectiveDescriptor(Directive, Kind, Usage, Tokens.ToArray(), DisplayName, Description);
             }
         }
 
@@ -227,12 +235,14 @@ private class DefaultDirectiveDescriptor : DirectiveDescriptor
             public DefaultDirectiveDescriptor(
                 string directive, 
                 DirectiveKind kind, 
+                DirectiveUsage usage,
                 DirectiveTokenDescriptor[] tokens,
                 string displayName,
                 string description)
             {
                 Directive = directive;
                 Kind = kind;
+                Usage = usage;
                 Tokens = tokens;
                 DisplayName = displayName;
                 Description = description;
@@ -246,6 +256,8 @@ public DefaultDirectiveDescriptor(
 
             public override DirectiveKind Kind { get; }
 
+            public override DirectiveUsage Usage { get; }
+
             public override IReadOnlyList<DirectiveTokenDescriptor> Tokens { get; }
         }
     }

src/Microsoft.AspNetCore.Razor.Language/DirectiveUsage.cs

@@ -0,0 +1,11 @@
+// Copyright(c) .NET Foundation.All rights reserved.
+// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
+
+namespace Microsoft.AspNetCore.Razor.Language
+{
+    public enum DirectiveUsage
+    {
+        Unrestricted,
+        SinglePreContent,
+    }
+}

src/Microsoft.AspNetCore.Razor.Language/IDirectiveDescriptorBuilder.cs

@@ -30,6 +30,11 @@ public interface IDirectiveDescriptorBuilder
         /// </summary>
         DirectiveKind Kind { get; }
 
+        /// <summary>
+        /// Gets the directive usage.
+        /// </summary>
+        DirectiveUsage Usage { get; set; }
+
         /// <summary>
         /// Gets a list of the directive tokens.
         /// </summary>

src/Microsoft.AspNetCore.Razor.Language/Legacy/BlockKindInternal.cs

@@ -8,13 +8,10 @@ public enum BlockKindInternal
         // Code
         Statement,
         Directive,
-        Functions,
         Expression,
-        Helper,
 
         // Markup
         Markup,
-        Section,
         Template,
 
         // Special

src/Microsoft.AspNetCore.Razor.Language/Legacy/CSharpCodeParser.cs

@@ -54,6 +54,7 @@ internal class CSharpCodeParser : TokenizerBackedParser<CSharpTokenizer, CSharpS
 
         private Dictionary<string, Action> _directiveParsers = new Dictionary<string, Action>(StringComparer.Ordinal);
         private Dictionary<CSharpKeyword, Action<bool>> _keywordParsers = new Dictionary<CSharpKeyword, Action<bool>>();
+        private HashSet<string> _seenDirectives = new HashSet<string>(StringComparer.Ordinal);
 
         public CSharpCodeParser(ParserContext context)
             : this(directives: Enumerable.Empty<DirectiveDescriptor>(), context: context)
@@ -91,7 +92,12 @@ protected void MapDirectives(Action handler, params string[] directives)
         {
             foreach (var directive in directives)
             {
-                _directiveParsers.Add(directive, handler);
+                _directiveParsers.Add(directive, () =>
+                {
+                    handler();
+                    _seenDirectives.Add(directive);
+                });
+
                 Keywords.Add(directive);
 
                 // These C# keywords are reserved for use in directives. It's an error to use them outside of
@@ -1589,10 +1595,13 @@ private void HandleDirective(DirectiveDescriptor descriptor)
                 AcceptAndMoveNext();
                 Output(SpanKindInternal.MetaCode, AcceptedCharactersInternal.None);
 
+                // Even if an error was logged do not bail out early. If a directive was used incorrectly it doesn't mean it can't be parsed.
+                ValidateDirectiveUsage(descriptor);
+
                 for (var i = 0; i < descriptor.Tokens.Count; i++)
                 {
                     if (!At(CSharpSymbolType.WhiteSpace) &&
-                        !At(CSharpSymbolType.NewLine) && 
+                        !At(CSharpSymbolType.NewLine) &&
                         !EndOfFile)
                     {
                         Context.ErrorSink.OnError(
@@ -1767,6 +1776,65 @@ private void HandleDirective(DirectiveDescriptor descriptor)
             }
         }
 
+
+        private void ValidateDirectiveUsage(DirectiveDescriptor descriptor)
+        {
+            if (descriptor.Usage == DirectiveUsage.SinglePreContent)
+            {
+                if (_seenDirectives.Contains(descriptor.Directive))
+                {
+                    UsageError(Resources.FormatDuplicateDirective(descriptor.Directive));
+                    return;
+                }
+
+                if (Context.Builder.ActiveBlocks.Count != 2)
+                {
+                    // 1 block for the root, 1 for the directive block, any more than 2 active blocks
+                    // means the directive is nested under another block.
+
+                    UsageError(Resources.FormatDirectiveMustExistBeforeMarkupOrCode(descriptor.Directive));
+                    return;
+                }
+
+                var root = Context.Builder.ActiveBlocks.Last();
+                for (var i = 0; i < root.Children.Count; i++)
+                {
+                    // Directives, comments and whitespace are valid prior to an unnested directive.
+
+                    var child = root.Children[i];
+                    if (child is Legacy.Block block)
+                    {
+                        if (block.Type == BlockKindInternal.Directive || block.Type == BlockKindInternal.Comment)
+                        {
+                            continue;
+                        }
+                    }
+                    else if (child is Span span)
+                    {
+                        if (span.Length == 0 ||
+                            span.Kind == SpanKindInternal.Comment ||
+                            span.Symbols.All(symbol => string.IsNullOrWhiteSpace(symbol.Content)))
+                        {
+                            continue;
+                        }
+                    }
+
+                    UsageError(Resources.FormatDirectiveMustExistBeforeMarkupOrCode(descriptor.Directive));
+                    return;
+                }
+            }
+
+            return;
+
+            void UsageError(string message)
+            {
+                // There wil always be at least 1 child because of the `@` transition.
+                var directiveStart = Context.Builder.CurrentBlock.Children.First().Start;
+                var errorLength = descriptor.Directive.Length + 1; // @directivename
+                Context.ErrorSink.OnError(directiveStart, message, errorLength);
+            }
+        }
+
         private void ParseDirectiveBlock(DirectiveDescriptor descriptor, Action<SourceLocation> parseChildren)
         {
             if (EndOfFile)

src/Microsoft.AspNetCore.Razor.Language/Legacy/SyntaxTreeBuilder.cs

@@ -17,7 +17,7 @@ public SyntaxTreeBuilder()
             _endBlock = EndBlock;
         }
 
-        public IEnumerable<BlockBuilder> ActiveBlocks => _blockStack;
+        public IReadOnlyCollection<BlockBuilder> ActiveBlocks => _blockStack;
 
         public BlockBuilder CurrentBlock => _blockStack.Peek();
 

src/Microsoft.AspNetCore.Razor.Language/Resources.resx

@@ -225,4 +225,10 @@
   <data name="IntermediateNodeReference_CollectionIsReadOnly" xml:space="preserve">
     <value>The node '{0}' has a read-only child collection and cannot be modified.</value>
   </data>
+  <data name="DuplicateDirective" xml:space="preserve">
+    <value>The '{0}' directive may only occurr once per document.</value>
+  </data>
+  <data name="DirectiveMustExistBeforeMarkupOrCode" xml:space="preserve">
+    <value>The '{0}' directive must exist prior to markup or code.</value>
+  </data>
 </root>

test/Microsoft.AspNetCore.Razor.Language.Test/Legacy/BlockTest.cs

@@ -30,7 +30,7 @@ public void ConstructorTransfersInstanceOfChunkGeneratorFromBlockBuilder()
             var expected = new ExpressionChunkGenerator();
             var builder = new BlockBuilder()
             {
-                Type = BlockKindInternal.Helper,
+                Type = BlockKindInternal.Statement,
                 ChunkGenerator = expected
             };
 
@@ -48,7 +48,7 @@ public void ConstructorTransfersChildrenFromBlockBuilder()
             var expected = new SpanBuilder(SourceLocation.Undefined) { Kind = SpanKindInternal.Code }.Build();
             var builder = new BlockBuilder()
             {
-                Type = BlockKindInternal.Functions
+                Type = BlockKindInternal.Statement
             };
             builder.Children.Add(expected);