Merge pull request #44 from apache/infrastructure-ruleset-bot/default-branch-protection
[INFRA] Set up default rulesets for default and release branches
diff --git a/_data/toc.json b/_data/toc.json
index d5ae7e9..8ceadc6 100644
--- a/_data/toc.json
+++ b/_data/toc.json
@@ -287,6 +287,9 @@
"path": "create-an-application/application-structure.md"
},
{
+ "path": "create-an-application/codegraphs.md"
+ },
+ {
"path": "create-an-application/application-tutorial.md",
"children": [
{
diff --git a/create-an-application.md b/create-an-application.md
index 2dcda54..ea10386 100644
--- a/create-an-application.md
+++ b/create-an-application.md
@@ -30,6 +30,8 @@
[Application Structure](create-an-application/application-structure) explains the important files that typically comprise an application and what they do.
+[Using codegraphs](create-an-application/codegraphs) explains how to generate a compiler-resolved description of your application's API and how development tools and AI models can use application and framework codegraphs.
+
[Application Tutorial](create-an-application/application-tutorial) is a step-by-step example of building an application.
[Migrate an Existing App](migrate-an-existing-app) provides strategies and techniques when migrating existing Flex apps to Royale, and how to switch to Royale if you already have a JavaScript application.
diff --git a/create-an-application/codegraphs.md b/create-an-application/codegraphs.md
new file mode 100644
index 0000000..a2916da
--- /dev/null
+++ b/create-an-application/codegraphs.md
@@ -0,0 +1,228 @@
+---
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+layout: docpage
+title: Using codegraphs
+description: Generate application codegraphs and use framework codegraphs to ground development tools and AI models
+permalink: /create-an-application/codegraphs
+---
+
+# Using codegraphs
+
+A codegraph is a deterministic JSON description of the public declarations and
+type relationships that the Royale compiler resolves for one build target. It
+records classes, interfaces, functions, members, signatures, inheritance,
+metadata, ASDoc, source provenance, and references between symbols. Framework
+aggregates also map Maven dependencies and MXML namespace tags.
+
+Because the compiler creates the graph, it reflects imports, external SWCs,
+visibility, inheritance, metadata, and conditional compilation. Separate
+JavaScript and SWF graphs describe the APIs that are actually available on each
+target.
+
+A codegraph is not a runtime call graph. It does not contain method bodies,
+application control flow, or data collected while an application runs. You do
+not need a codegraph to compile, run, or deploy an application.
+
+## Why codegraphs are useful
+
+Development tools can use codegraphs without reparsing ActionScript and MXML
+source. For example, a tool can:
+
+* provide completion and navigation;
+* find inherited members and related types;
+* resolve MXML tags to their ActionScript classes;
+* generate API documentation;
+* compare public APIs between releases; and
+* identify APIs that are available only for JavaScript or SWF.
+
+Codegraphs are particularly useful for AI-assisted development. A general AI
+model may know little about the version of Royale used by an application, may
+confuse Royale APIs with Apache Flex APIs, or may invent members that sound
+plausible. A codegraph supplies compiler-resolved facts that a tool can retrieve
+and place in the model's context before asking it to explain or generate code.
+
+This grounding can help an AI tool answer questions such as:
+
+* Which component implements a particular interface?
+* Which properties and events are available on an MXML tag?
+* Is a member available for the application's current target?
+* What constructor parameters or method arguments are required?
+* Which package contains the type that should be imported?
+
+The model still produces probabilistic output. The application should still be
+compiled and tested, but codegraph grounding substantially reduces guessing
+about API names, signatures, inheritance, and target availability.
+
+## Consume framework codegraphs
+
+Use the framework graph bundle that exactly matches the application's Royale
+version. Released framework graphs are build metadata and are separate from the
+SWCs that an application links.
+
+| Installation | Framework codegraph location |
+| --- | --- |
+| Binary SDK | `$ROYALE_HOME/frameworks/codegraphs` |
+| npm SDK | `<package>/royale-asjs/frameworks/codegraphs` |
+| Maven | `org.apache.royale.framework:distribution:zip:codegraphs:<version>` |
+
+The aggregate contains:
+
+```text
+index.json
+mxml.json
+<version>/<module>/<js|swf>/<module>.json
+```
+
+`index.json` lists modules, dependencies, available targets, shard paths, and
+SHA-256 hashes. `mxml.json` maps namespace tags to graph symbols. Each module
+shard contains the public API for one compiler target.
+
+A consumer should:
+
+1. Read `index.json` and reject unsupported schema major versions.
+2. Select `js` or `swf` to match the application build.
+3. Select the application's direct and transitive framework modules.
+4. Load only those module shards and verify their SHA-256 hashes.
+5. Read `mxml.json` when MXML tag lookup is needed.
+6. Resolve relationships by stable symbol ID rather than by simple name or
+ source-file path.
+
+Do not copy the complete framework aggregate into every application or deploy
+it with the application. Cache each released aggregate once by framework
+version and schema version, then let projects share that cache.
+
+## Ground an AI model
+
+Do not send the entire framework aggregate to an AI model. It is too large and
+most of it will be irrelevant to a particular question. Use the codegraphs as a
+retrieval source:
+
+1. Determine the application's framework version, target, and dependencies.
+2. Resolve MXML tags, qualified names, and stable symbol IDs mentioned in the
+ question or current source file.
+3. Follow only useful edges, such as base types, interfaces, member parameter
+ types, return types, events, and styles.
+4. Convert the selected records into a compact text or structured-data context.
+5. Ask the model to use only the supplied API facts and to identify any
+ unresolved symbol instead of guessing.
+6. Compile and test generated code.
+
+For application-aware assistance, index the application's graph alongside the
+matching framework shards. Keep the artifacts separate and compose them in the
+retrieval layer through stable references. This lets the model understand both
+project-specific APIs and the framework without creating a large merged copy.
+
+Codegraphs contain API documentation and source provenance. Before sending
+application graph content to an external AI service, apply the same privacy and
+source-code policies that you use for application source.
+
+## Generate an application codegraph
+
+Generate an application graph when an editor, documentation system, analysis
+tool, or AI retrieval service needs to understand the application's API. Use the
+same compiler configuration, source paths, library paths, namespaces, and
+conditional defines as the normal application build.
+
+### Maven
+
+Add the `compile-codegraph` goal to the existing Royale compiler plugin
+configuration:
+
+```xml
+<plugin>
+ <groupId>org.apache.royale.compiler</groupId>
+ <artifactId>royale-maven-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>codegraph</id>
+ <phase>prepare-package</phase>
+ <goals>
+ <goal>compile-codegraph</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin>
+```
+
+The goal writes the project-owned graph beneath `target/codegraph`. Keep this
+graph separate from downloaded framework graph bundles.
+
+### Ant
+
+An Ant application can invoke the codegraph compiler client directly. This
+example assumes `ROYALE_COMPILER_HOME` identifies the compiler in the SDK and
+the application already has a compiler configuration file.
+
+```xml
+<property environment="env"/>
+<property name="ROYALE_HOME" value="${env.ROYALE_HOME}"/>
+<property name="ROYALE_COMPILER_HOME" value="${env.ROYALE_COMPILER_HOME}"/>
+
+<target name="codegraph-js">
+ <mkdir dir="${basedir}/target/codegraph/js"/>
+ <java jar="${ROYALE_COMPILER_HOME}/lib/codegraph.jar"
+ fork="true" failonerror="true">
+ <jvmarg value="-Xmx512m"/>
+ <jvmarg value="-Droyalecompiler=${ROYALE_COMPILER_HOME}"/>
+ <jvmarg value="-Droyalelib=${ROYALE_HOME}/frameworks"/>
+ <arg value="-load-config=${basedir}/src/main/config/compile-js-config.xml"/>
+ <arg value="-compiler.define+=COMPILE::JS,true"/>
+ <arg value="-compiler.define+=COMPILE::SWF,false"/>
+ <arg value="-keep-asdoc=true"/>
+ <arg value="-output=${basedir}/target/codegraph/js/MyApplication.json"/>
+ <arg value="${basedir}/src/main/royale/MyApplication.mxml"/>
+ </java>
+</target>
+```
+
+For a SWF graph, load the SWF configuration, set `COMPILE::JS` to `false` and
+`COMPILE::SWF` to `true`, and use a separate output directory.
+
+### Command line
+
+The installed compiler provides `bin/codegraph` (`bin/codegraph.bat` on
+Windows). In an SDK, the script is normally available at
+`$ROYALE_HOME/js/bin/codegraph`.
+
+```bash
+$ROYALE_COMPILER_HOME/bin/codegraph \
+ -load-config=/path/to/compile-js-config.xml \
+ -compiler.define+=COMPILE::JS,true \
+ -compiler.define+=COMPILE::SWF,false \
+ -keep-asdoc=true \
+ -output=target/codegraph/js/MyApplication.json \
+ src/main/royale/MyApplication.mxml
+```
+
+The positional source file is optional. When present, its base name becomes the
+module name and it is included as a graph root. Without it, use
+`-include-sources` or `-include-classes` to configure roots; the output file's
+base name becomes the module name.
+
+| Argument | Purpose |
+| --- | --- |
+| `-load-config=<file>` | Load the application's normal compiler configuration. Use `+=` to append another configuration. |
+| `-output=<file>` | Set the JSON output path. |
+| `-compiler.define+=NAME,VALUE` | Supply conditional values, including `COMPILE::JS` and `COMPILE::SWF`. |
+| `-include-sources+=<path>` | Add a source file or directory as a graph root. |
+| `-include-classes+=<name>` | Add a qualified class as a graph root. |
+| `-keep-asdoc=true` | Include parsed ASDoc in the graph. |
+| `-create-target-with-errors=true` | Permit output after compiler errors. Omit this for trusted build metadata. |
+
+All normal compiler path, namespace, define, and external-library options are
+accepted. A graph is trustworthy only when those options match the application
+artifact that it describes.
\ No newline at end of file
diff --git a/features/as3/metadata.md b/features/as3/metadata.md
index 58a0934..1e8ca41 100644
--- a/features/as3/metadata.md
+++ b/features/as3/metadata.md
@@ -455,6 +455,159 @@
InstanceType
+## JSDynamicOverride
+
+_Available since Royale 1.0.0_
+
+ActionScript supports dynamically accessing object keys using square brackets, removing keys with the `delete` keyword, and checking whether a key exists with the `in` keyword. For most objects, those keys are strings. Arrays typically use integers for keys. When targeting SWF, the `flash.utils.Dictionary` class supports keys of any type.
+
+To support any type of keys when targeting JavaScript, the `[JSDynamicOverride]` metadata may be used to inform the compiler that it should translate dynamic code to method calls. There are a number of method names that may be set on this meta. All are optional, and none require any others.
+
+- `getMethod` translates `object[key]` reads
+- `setMethod` translates `object[key]` writes
+- `deleteMethod` translates `delete object[key]` removals
+- `inMethod` translates `key in object` conditions
+
+The following example demonstrates how to add this metadata to a class, along
+with sample method signatures.
+
+```as3
+[JSDynamicOverride(getMethod="getKey",setMethod="setKey",deleteMethod="deleteKey",inMethod="keyIn")]
+public interface DynamicLookup {
+ public function getKey(key:Object):Object {
+ // implementation
+ }
+
+ public function setKey(key:Object, value:Object):Object {
+ // implementation
+ }
+
+ public function deleteKey(key:Object):Boolean {
+ // implementation
+ }
+
+ public function keyIn(key:Object):Boolean {
+ // implementation
+ }
+}
+```
+
+The next example shows how the class above might be used:
+
+```as3
+var valueToStore:Number = 123.4;
+var key:Object = {};
+
+var obj:DynamicLookup = new DynamicLookup();
+obj[key] = valueToStore;
+
+var valueThatWasStored:Number = lookup[key];
+assertTrue(valueToStore == valueThatWasStored); // true
+
+if (key in lookup) {
+ delete lookup[key];
+}
+```
+
+When the compiler generates JavaScript from the code above, its translation will look roughly similar to the following:
+
+```js
+var valueToStore = 123.4;
+var key = {};
+
+var obj = new DynamicLookup();
+obj.setKey(key, valueToStore);
+
+var valueThatWasStored = obj.getKey(key);
+assertTrue(valueToStore == valueThatWasStored); // true
+
+if (lookup.keyIn(key)) {
+ lookup.deleteKey(key);
+}
+```
+
+## JSForEachOverride
+
+_Available since Royale 1.0.0_
+
+ActionScript supports looping through the values of an array or collection using the `for-each` loop. When targeting SWF, `for-each` loops may provide special behavior for classes like `flash.utils.Dictionary`.
+
+To support iterating over the values of custom types when targeting JavaScript, the `[JSForEachOverride]` metadata may be used to inform the compiler that it should translate `for-each` loop code to method calls. There are a number of method names that may be set on this meta. All are optional, and none require any others.
+
+- `iteratorMethod` creates an iterator object
+- `iteratorNextMethod` returns the next value from the iterator object
+- `iteratorHasNextMethod` determines if the iterator has additional values
+- `iteratorDoneMethod` determines if the iterator has no additional values
+
+Generally, the metadata should define either `iteratorHasNextMethod` or `iteratorDoneMethod`, but not both. These properties exist to support both styles if checking if the iterator can continue or not. Alternately, you may omit both method names, and the compiler will check if the result of the `iteratorNextMethod` is `null` to determine when the loop has completed. However, this prevents looping over a collection that may contain `null` values.
+
+The following example demonstrates how to add this metadata to a class, along
+with sample method signatures. It uses `iteratorHasNextMethod`.
+
+```as3
+[JSForEachOverride(iteratorMethod="getIterator",iteratorNextMethod="getNext",iteratorHasNextMethod="hasNext")]
+class DynamicForEach {
+ public function getIterator():Object {
+ return new DynamicForEachIterator(this);
+ }
+}
+
+class DynamicForEachIterator {
+ public function DynamicForEachIterator(target:DynamicForEach) {
+ // implementation
+ }
+
+ public function getNext():Object {
+ // implementation
+ }
+
+ public function hasNext():Boolean {
+ // implementation
+ }
+}
+```
+
+## JSForInOverride
+
+_Available since Royale 1.0.0_
+
+ActionScript supports looping through object keys using the `for-in` loop. For most objects, those keys are strings. Arrays typically use integers for keys. When targeting SWF, the `flash.utils.Dictionary` class supports keys of any type.
+
+To support iterating over any type of keys when targeting JavaScript, the `[JSForInOverride]` metadata may be used to inform the compiler that it should translate `for-in` loop code to method calls. There are a number of method names that may be set on this meta. All are optional, and none require any others.
+
+- `iteratorMethod` creates an iterator object
+- `iteratorNextMethod` returns the next key from the iterator object
+- `iteratorHasNextMethod` determines if the iterator has additional keys
+- `iteratorDoneMethod` determines if the iterator has no additional keys
+
+Generally, the metadata should define either `iteratorHasNextMethod` or `iteratorDoneMethod`, but not both. These properties exist to support both styles if checking if the iterator can continue or not. Alternately, you may omit both method names, and the compiler will check if the result of the `iteratorNextMethod` is `null` to determine when the loop has completed. However, this prevents looping over a collection that may contain `null` values.
+
+The following example demonstrates how to add this metadata to a class, along
+with sample method signatures. It uses `iteratorHasNextMethod`.
+
+```as3
+[JSForInOverride(iteratorMethod="getIterator",iteratorNextMethod="getNext",iteratorHasNextMethod="hasNext")]
+class DynamicForIn {
+ public function getIterator():Object {
+ return new DynamicForInIterator(this);
+ }
+}
+
+class DynamicForInIterator {
+ public function DynamicForInIterator(target:DynamicForIn) {
+ // implementation
+ }
+
+ public function getNext():Object {
+ // implementation
+ }
+
+ public function hasNext():Boolean {
+ // implementation
+ }
+}
+```
+
## JSIncludeAsset
_Available since Royale 0.9.13_
@@ -498,6 +651,40 @@
In the output directory, typically _bin/js-debug_ or _bin/js-release_, the _index.html_ file will be generated in the root, and _.js_ files will be copied into a _scripts_ sub-directory.
+### JSModule
+
+_Available since Royale 0.9.7_
+
+When targeting a JavaScript runtime that supports CommonJS modules, like Node.js, you may need to access external modules. You can define classes with `@externs` to indicate that they will be available in global scope at run-time, rather than compiled from ActionScript to JavaScript. To indicate that that an extern is located in a module, use `[JSModule]` metadata. The `name` property may be used to indicate the name of the module to require.
+
+```as3
+[JSModule(name="mymodule")]
+/**
+ * @externs
+ */
+public class MyClass {}
+```
+
+When the compiler generates JavaScript code, it will import the module using `require()`.
+
+```js
+var MyClass = require("mymodule");
+```
+
+### JSX
+
+_Available since Royale 0.9.7_
+
+ActionScript has traditionally supported an inline XML syntax named E4X. JSX is another form of inline XML that was created for JavaScript frameworks like React, and its syntax largely overlaps with E4X. `[JSX]` metadata may be added to a method to treat any inline XML that the method contains as JSX instead of E4X.
+
+```as3
+[JSX]
+public function methodWithJSX():void
+{
+ return <MyComponent/>;
+}
+```
+
### Managed
Managed
