[macros] Specify that identifiers in strings must refer to locals. (#2076)

* [macros] Specify that identifiers in strings must refer to locals.

* Clarify how bare identifiers in composed Code objects are resolved.

* Identifiers in strings resolve where the generated code ends up.

Author: munificent

working/macros/feature-specification.md

@@ -4,6 +4,11 @@ Authors: Jacob MacDonald, Bob Nystrom
 
 Status: **Work In Progress**
 
+### Changelog
+
+- *2022/01/25:* Specify that identifiers in strings can only refer to local
+  declarations.
+
 ## Introduction
 
 The [motivation][] document explains why we are working on static
@@ -532,7 +537,7 @@ challenges still remain.
 
 #### Referring to generated declarations
 
-A key use of macros is generating new declarations. Since this declarations
+A key use of macros is generating new declarations. Since these declarations
 aren't useful if not called, it implies that handwritten code may contain
 references to declarations produced by macros. This means that before macros are
 applied, code may contain identifiers that cannot be resolved.
@@ -617,31 +622,40 @@ macros to library augmentations.
 
 #### Resolving identifiers in generated code
 
-Macros will likely want to introduce references to identifiers that are not in
-the scope of the library in which they are running, but are in the scope of the
-macro itself, or possibly even references which are not in scope of either the
-macro itself or the library where it is applied.
-
-Even if an identifier is in scope of the library in which the macro is applied
-(let's say its exported by the macro library), that identifier could be shadowed
-by another identifier in the library.
-
-To enable a macro to safely emit a reference to a known identifier, there is
-a `Identifier` subtype of `Code`. This class takes both a simple name for the
-identifier (no prefix allowed), as well as a library URI, where that identifier
-should be looked up.
-
-The generated code should be equivalent to adding a new import to the library,
-with the specified URI and a unique prefix. In the code the identifier will be
-emitted with that unique prefix followed by its simple name.
-
-Note that technically this allows macros to add references to libraries that
-the macro itself does not depend on, and the users application also may not
-depend on. This is discouraged, but not prevented, and should result in an error
-if it happens.
-
-**TODO**: Investigate other approaches, see [this
-comment](https://github.com/dart-lang/language/pull/1779#discussion_r683843130).
+When a macro generates code containing an identifier, the identifier must be
+resolved in the context of some namespace to determine what declaration it
+refers to. It's not enough to simply resolve generated code in the same
+namespace where the macro is applied. The macro author may want to, for example,
+generate a call to a utility function that the macro author knows about but that
+the library applying the macro is unaware of. Or a macro may want to generate
+code that creates an instance of some class that is an implementation detail of
+the macro and not in scope where the macro is applied.
+
+To support this, there is an `Identifier` subtype of `Code`. An instance of this
+class represents an identifier resolved in the context of a known library's
+namespace. When the `Identifier` object is inserted into other generated code,
+it retains its original resolution.
+
+*A compiler could implement this by generating an import of the library
+containing the declaration that the identifier refers to. The compiler adds a
+unique prefix to the import and then the identifier emitted as a prefixed
+identifier followed by the identifier's simple name.*
+
+Macros also build generated code using strings. Identifiers that appear in bare
+strings are resolved where they appear in the generated code, and where that
+generated code appears in the library, after all macros in the library have
+finished executing. For example, if a macro is generating the body of an
+instance method, an identifier in a string used to build that body might resolve
+to a local variable declared inside that method, to an instance member on the
+surrounding class (which may or may not have been produced by some macro), to a
+static method, or to a top level identifier.
+
+If a macro wants to generate code containing an identifier that unambigiously
+refers to a top level declaration and can't inadvertently capture a local
+variable in surrounding generated code, the macro can create an `Identifier` for
+that top level declaration and insert that into the generated code.
+
+**TODO: Define this API. See [here](https://github.com/dart-lang/language/pull/1779#discussion_r683843130).**
 
 ### Generating macro applications