docs(metadat): bundle metadata shape #2 @W-7263561@ (#34)

* docs(metadat): bundle metadata shape #2

* wip: add documentation

* wip: second pass

* wip: review comments

* wip: correct types

Author: apapko

text/0000-canonical-metadata.md

@@ -1216,6 +1216,240 @@ interface StaticResourceReference {
 ```
 </details>
 
+## Metadata Shape Option 2
+Overview:
+The vision is to allow expert users to retrieve file based metadata and for the regular users to retrieve an easy, self-contained metadata object that exposes all publicly available/accessible properties of the current bundle.
+
+The main differences in proposed shape #2:
+- no decorators: external consumer shouldn't be concerned if the class fields are decorated or not. All they need is the information that describes whether the class member is public. With that, instead of collecting decorators, each class member will carry 'isPublic' property to indicate its access. 
+- success: an indication of successful collection. If errors occurred during the metadata collection, then 'success' will be false and diagnostics will be reported.
+- diagnostics: even though metadata collection is not responsible for validating the syntax, any unexpected failures during the collection should be handled gracefully and surfaced to the user
+- javascript declarations: file metadata revolves around declarations (both exported and private) - that can be functions, classes, consts, etc. The reason for this is that we don't know the content of the file and cannot make an assumption about its shape, therefore the metadata is collected from declarations.
+- bundle interface: an interpretation of the bundle shape. It is an object that contains public properties, slots, events or anything that is accessible from the outside of the component/module. The reason for doing so is that individual file metadata doesn't have the notion of other files in the bundle and therefore cannot make assumption about an overall shape. With that, the interface is an additional step that attempts to deduce the shape and provide a union of all public properties. 
+
+### TypeScript
+
+#### Root Metadata Object
+```ts
+interface BundleMetadata {
+    success: boolean;
+    version: string;
+    diagnostics: Array<Diagnostic>;
+    entry: string;
+    results: { [name: string]: FileMetadata } // metadata for each source
+    interface: BundleInterface; // public methods, events, css properties, exports, slots.
+}
+
+interface Diagnostic {
+    message: string;
+    code: number;
+    filename?: string;
+    location?: Location;
+    level: DiagnosticLevel;
+}
+
+enum DiagnosticLevel { Fatal, Error, Warning, Log }
+
+// A bundle interface; which contains a union of all file-based
+// metadata objects with some wits about inheritance and overrides. 
+interface BundleInterface {
+    type: 'module' | 'component';
+    eventListener: Array<EventListener>;
+    emittedEvents: Array<ClassEvent>;
+    publicProperties: Array<ClassMember>;
+    publicMethods: Array<ClassMember>;
+    slots: Array<SlotMeta>;
+    exports: Array<ClassMetadata | FunctionMetadata | VariableMetadata>
+}
+```
+
+<details>
+<summary>Click to view format</summary>
+
+#### Root Metadata Object Per File
+```ts
+interface FileMetadata {
+    name: string,
+    path: string;
+    type: 'script' | 'html'| 'css',
+    dependencies: Array<Reference>, // dynamic import is treated as a module dependency type of 'dynamic'
+}
+
+interface Reference {
+    type: ReferenceType;
+    id: string;
+    namespacedId?: string;
+    file: string;
+    locations: Location[];
+}
+interface ReferenceReport {
+    references: Reference[];
+    diagnostics: Diagnostic[];
+}
+type ReferenceType = 'apexClass' | 'apexMethod' | 'apexContinuation' | 'client' | 'community' | 'component' | 'contentAssetUrl' | 'customPermission' | 'dynamicComponent' | 'slds' | 'messageChannel' | 'i18n' | 'gate' | 'label' | 'metric' | 'module' | 'internal' | 'resourceUrl' | 'schema' | 'sobjectClass' | 'sobjectField' | 'user' | 'userPermission';
+```
+
+For every source in the bundle there will be a corresponding typed class which extends from the base FileMetadata.
+
+#### Script Metadata (.js|.ts)
+```ts
+interface ScriptMetadata extends FileMetadata {
+    type: 'script';
+    declarations: Array<ClassMetadata | FunctionMetadata | VariableMetadata>
+} 
+
+interface FunctionMetadata {
+    name?: string;
+    params?: Array<any>;
+    returnValue?: ClassMemberValue;
+    context?: ClassMemberValue; // invocation context
+}
+
+interface VariableMetadata {
+    name?: string;
+    value?: ClassMemberValue;
+}
+
+interface ClassMetadata {
+   name?: string; // optional due to anonymous class
+   extends: ExtendsMeta; // id; resource; location of the super 
+   classMembers: Array<ClassMember>; // includes private/public props/methods
+   documentation: ClassDocumentation;
+   events: Array<ClassEvent>;
+   listeners: Array<ClassListener> // programmatic or declarative event listeners found in the file
+}
+
+interface ClassEvent {
+    name: string;
+    className: string; // class the event is fired from 
+    location: Location;
+}
+
+interface ClassListener {
+    name: string;
+    handlerName: string;
+    className: string; // class the event is fired from 
+    location: Location;
+}
+
+interface ClassDocumentation {
+    classDescription: string;
+    html: string;
+    metadata: Object;
+}
+
+interface ExtendsMeta {
+    id: string;
+    type: 'class' | 'function';
+    resource: string;
+    location: Location;
+}
+
+interface ClassMember {
+    name: string;
+    type: string;
+    isPublic: boolean;
+    documentation?: ClassMemberDocumentation;
+    wire?: WireDependency
+}
+
+interface ClassMemberDocumentation {
+    description: string;
+    defaultValue: string;
+    dataType: string;
+    isRequired: boolean
+}
+
+interface ClassProperty extends ClassMember {
+    hasGetter: boolean;
+    hasSetter: boolean;
+    value?: ClassMemberValue;
+}
+
+interface ClassMethod extends ClassMember {
+    returnValue?: ClassMemberValue;
+}
+
+interface ClassMemberValue {
+    type: ClassMemberValueType; 
+    value: any;
+    importedName: string;
+}
+
+enum ClassMemberValueType {
+    ARRAY, BOOLEAN, MODULE, NUMBER, NULL, OBJECT, STRING, UNDEFINED, UNRESOLVED,
+}
+
+interface WireDependency {
+    adapter: WireTargetAdapter;
+    params?: { [name: string]: ClassMemberValue }; // value has type and actual value
+    
+}
+
+interface WireTargetAdapter {
+    adapterId: string;
+    moduleSpecifier: string; // points to the adapter resource
+}
+
+interface SlotMeta {
+    name: string;
+    scope: string; // parent element name
+}
+```
+
+### HTML Metadata
+```ts
+interface HTMLMetadata extends FileMetadata {
+    type: 'html';
+    tags: Array<CustomElementMetadata>;
+    slots: Array<SlotMeta>;
+    staticResources: Array<Reference>, //images, urls, etc with location
+}
+
+interface CustomElementMetadata {
+    attributes: {
+        [name: string]: DependencyParameter;
+    };
+    properties: {
+        [name: string]: DependencyParameter;
+    };
+    events: Array<HTMLEventListener>, // not sure if the even belongs to a js or html meta
+}
+
+interface DependencyParameter {
+    type: 'literal' | 'expression';
+    value: string | boolean;
+}
+
+interface HTMLEventListener {
+    name: string;
+    handlerName: string;
+    tagName: string; // custom element the handle is attached to
+    location: Location;
+}
+```
+
+### CSS Metadata 
+```ts
+interface CSSMetadata extends FileMetadata {
+    type: 'css';
+    imports: Array<Reference>; // css only module imports
+    customProperties: Array<CssCustomProperty>;
+}
+
+interface CssCustomProperty {
+    external: boolean; // determines if the custom property is defined in the current file
+    name: string;
+    fallback: string;
+    value?: {
+        type: string;
+        value: string;
+        fallback: string;
+    }
+}
+```
+</details>
+
 # Open questions
 * Should gathering metadata about configuration(`*.js-meta.xml`) file in a bundle be in the scope of this RFC?
   * Dean Moses from Builder Framework team says it is not required.
@@ -1229,4 +1463,4 @@ interface StaticResourceReference {
 - [JSON Schema type system](https://salesforce.quip.com/SH2FA614DXQO)<sup>*</sup>
 - [RFC - Canonical View Metadata](https://salesforce.quip.com/ZJ93A0XQZvnU)<sup>*</sup>
 
-<sup>*</sup> _restricted access_
+<sup>*</sup> _restricted access_