From 172bfc3e3699a5530b357852db245079bce01c93 Mon Sep 17 00:00:00 2001 From: Chidozie Ononiwu Date: Thu, 18 Jul 2024 10:21:18 -0700 Subject: [PATCH] Add TypeSpec Definition for APIView TreeStyle Parser --- .../json-schema/APITreeNode.json | 90 +++++++++++ .../json-schema/APITreeNodeProperties.json | 11 ++ .../json-schema/APITreeNodeTags.json | 31 ++++ .../json-schema/CodeDiagnostic.json | 30 ++++ .../json-schema/CodeDiagnosticLevel.json | 12 ++ .../json-schema/StructuredToken.json | 41 +++++ .../json-schema/StructuredTokenKind.json | 12 ++ .../StructuredTokenProperties.json | 16 ++ .../StructuredTokenRenderClasses.json | 50 ++++++ .../json-schema/StructuredTokenTags.json | 16 ++ .../models.tsp | 150 ++++++++++++++++++ 11 files changed, 459 insertions(+) create mode 100644 tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNode.json create mode 100644 tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeProperties.json create mode 100644 tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeTags.json create mode 100644 tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeDiagnostic.json create mode 100644 tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeDiagnosticLevel.json create mode 100644 tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredToken.json create mode 100644 tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenKind.json create mode 100644 tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenProperties.json create mode 100644 tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenRenderClasses.json create mode 100644 tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenTags.json create mode 100644 tools/apiview/parsers/apiview-treestyle-parser-schema/models.tsp diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNode.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNode.json new file mode 100644 index 000000000000..2d3d2a9a47a1 --- /dev/null +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNode.json @@ -0,0 +1,90 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "APITreeNode.json", + "type": "object", + "properties": { + "Name": { + "type": "string", + "description": "The name of the tree node which will be used as label for the API Navigation. Generally this is the name of the module (class, method)." + }, + "Id": { + "type": "string", + "description": "Id of the node, which should be unique at the node level. i.e. unique among its siblings. This was previously represented by the DefinitionId for the main Token of the node." + }, + "Kind": { + "anyOf": [ + { + "type": "string", + "const": "assembly" + }, + { + "type": "string", + "const": "namespace" + }, + { + "type": "string", + "const": "class" + }, + { + "type": "string", + "const": "delegate" + }, + { + "type": "string", + "const": "enum" + }, + { + "type": "string", + "const": "interface" + }, + { + "type": "string", + "const": "method" + }, + { + "type": "string", + "const": "package" + }, + { + "type": "string", + "const": "struct" + }, + { + "type": "string", + "const": "type" + } + ], + "description": "The kind of node" + }, + "BottomTokens": { + "type": "array", + "items": { + "$ref": "StructuredToken.json" + }, + "description": "Tokens which are rendered after all child nodes. Depending on the language this would include the closing curly brace and/or empty lines." + }, + "Children": { + "type": "array", + "items": { + "$ref": "APITreeNode.json" + }, + "description": "The nodes immediate children. For a namespace this would be classes, for a class this would be the class constructors and methods. Children are rendered after TopTokens but before BottomTokens, and are automatically indented." + }, + "Properties": { + "$ref": "APITreeNodeProperties.json", + "description": "Properties of the APITreeNode." + }, + "Tags": { + "type": "array", + "items": { + "$ref": "APITreeNodeTags.json" + }, + "description": "Tags of the APITreeNode." + } + }, + "required": [ + "Name", + "Id", + "Kind" + ] +} \ No newline at end of file diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeProperties.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeProperties.json new file mode 100644 index 000000000000..dddef5f64c95 --- /dev/null +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeProperties.json @@ -0,0 +1,11 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "APITreeNodeProperties.json", + "type": "object", + "properties": { + "IconName": { + "type": "string", + "description": "Use this only if you are looking to add a custom icon different from language wide defaults set by APITreeNode kind" + } + } +} \ No newline at end of file diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeTags.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeTags.json new file mode 100644 index 000000000000..ee874511c034 --- /dev/null +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeTags.json @@ -0,0 +1,31 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "APITreeNodeTags.json", + "anyOf": [ + { + "type": "string", + "const": "Deprecated", + "description": "Mark a token as deprecated." + }, + { + "type": "string", + "const": "Hidden", + "description": "Mark a node as Hidden." + }, + { + "type": "string", + "const": "HideFromNav", + "description": "Indicate that a node should be hidden from the page navigation." + }, + { + "type": "string", + "const": "SkipDiff", + "description": "Indicate that a node should not be used in computation of diff." + }, + { + "type": "string", + "const": "CrossLangDefId", + "description": "The cross language definitionId for the node." + } + ] +} \ No newline at end of file diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeDiagnostic.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeDiagnostic.json new file mode 100644 index 000000000000..a91c6e299730 --- /dev/null +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeDiagnostic.json @@ -0,0 +1,30 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "CodeDiagnostic.json", + "type": "object", + "properties": { + "DiagnosticId": { + "type": "string" + }, + "Text": { + "type": "string" + }, + "HelpLinkUri": { + "type": "string" + }, + "TargetId": { + "type": "string", + "description": "Maps to the APITreeNode id" + }, + "Level": { + "$ref": "CodeDiagnosticLevel.json" + } + }, + "required": [ + "DiagnosticId", + "Text", + "HelpLinkUri", + "TargetId", + "Level" + ] +} \ No newline at end of file diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeDiagnosticLevel.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeDiagnosticLevel.json new file mode 100644 index 000000000000..6e6381705e4e --- /dev/null +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeDiagnosticLevel.json @@ -0,0 +1,12 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "CodeDiagnosticLevel.json", + "type": "string", + "enum": [ + "Default", + "Info", + "Warning", + "Error", + "Fatal" + ] +} \ No newline at end of file diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredToken.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredToken.json new file mode 100644 index 000000000000..78847620a5d7 --- /dev/null +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredToken.json @@ -0,0 +1,41 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "StructuredToken.json", + "type": "object", + "properties": { + "Id": { + "type": "string", + "description": "Token Id. Previously known as DefinitionId." + }, + "Kind": { + "$ref": "StructuredTokenKind.json", + "description": "Represents the type of a structured token" + }, + "Value": { + "type": "string", + "description": "The token value which will be displayed. Spacing tokens (LineBreak, NonBreakingSpace, TabSpace, and ParameterSeparator) don't need to have value" + }, + "Properties": { + "$ref": "StructuredTokenProperties.json", + "description": "Properties of the StructuredToken." + }, + "Tags": { + "type": "array", + "items": { + "$ref": "StructuredTokenTags.json" + }, + "description": "Tags of the StructuredToken." + }, + "RenderClasses": { + "type": "array", + "items": { + "$ref": "StructuredTokenRenderClasses.json" + }, + "description": "Classes used to render the StructuredTokens." + } + }, + "required": [ + "Id", + "Kind" + ] +} \ No newline at end of file diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenKind.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenKind.json new file mode 100644 index 000000000000..356125111bad --- /dev/null +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenKind.json @@ -0,0 +1,12 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "StructuredTokenKind.json", + "type": "string", + "enum": [ + "Content", + "LineBreak", + "NonBreakingSpace", + "TabSpace", + "ParameterSeparator" + ] +} \ No newline at end of file diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenProperties.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenProperties.json new file mode 100644 index 000000000000..b2b4d32f5326 --- /dev/null +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenProperties.json @@ -0,0 +1,16 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "StructuredTokenProperties.json", + "type": "object", + "properties": { + "GroupId": { + "type": "string", + "const": "doc", + "description": "Group a sequence of consecutive StructuredTokens. doc indicates that the group of tokens is documentation." + }, + "NavigateToId": { + "type": "string", + "description": "Id to navigate to when StructuredToken is clicked." + } + } +} \ No newline at end of file diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenRenderClasses.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenRenderClasses.json new file mode 100644 index 000000000000..cb6d222231d9 --- /dev/null +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenRenderClasses.json @@ -0,0 +1,50 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "StructuredTokenRenderClasses.json", + "anyOf": [ + { + "type": "string", + "const": "comment" + }, + { + "type": "string", + "const": "keyword" + }, + { + "type": "string", + "const": "keyword" + }, + { + "type": "string", + "const": "literal" + }, + { + "type": "string", + "const": "sliteral", + "description": "string literal" + }, + { + "type": "string", + "const": "mname", + "description": "member name" + }, + { + "type": "string", + "const": "tname", + "description": "type name" + }, + { + "type": "string", + "const": "punc", + "description": "punctuation" + }, + { + "type": "string", + "const": "text" + }, + { + "type": "string" + } + ], + "description": "Classes used to render the StructuredTokens. Extendable by contributing styles at https://github.com/Azure/azure-sdk-tools/blob/main/src/dotnet/APIView/ClientSPA/src/app/_components/code-panel/code-panel.component.scss" +} \ No newline at end of file diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenTags.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenTags.json new file mode 100644 index 000000000000..088027e11089 --- /dev/null +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenTags.json @@ -0,0 +1,16 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "StructuredTokenTags.json", + "anyOf": [ + { + "type": "string", + "const": "Deprecated", + "description": "Mark a token as deprecated" + }, + { + "type": "string", + "const": "SkipDiff", + "description": "Indicate that a Token should not be used in computing diff" + } + ] +} \ No newline at end of file diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/models.tsp b/tools/apiview/parsers/apiview-treestyle-parser-schema/models.tsp new file mode 100644 index 000000000000..df683a8927e8 --- /dev/null +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/models.tsp @@ -0,0 +1,150 @@ +model CodeFile { + /** The version of the parser */ + VersionString: string; + + /** Name the ocde file. Usually just the package name and version*/ + Name: string; + + Language: string; + LanguageVariant: "Default" | "Spring" | "Android"; + PackageName: string; + ServiceName: string; + PackageVersion: string; + + /** Maps related packages across Languages */ + CrossLanguagePackageId: string; + + /** The API Tree(s) */ + APIForest: APITreeNode[]; + + Diagnostics: CodeDiagnostic[]; +} + +model CodeDiagnostic { + DiagnosticId: string; + Text: string; + HelpLinkUri: string; + + /** Maps to the APITreeNode id */ + TargetId: string; + Level: CodeDiagnosticLevel; +} + +model APITreeNode { + /** The name of the tree node which will be used as label for the API Navigation. Generally this is the name of the module (class, method). */ + Name: string; + + /** Id of the node, which should be unique at the node level. i.e. unique among its siblings. This was previously represented by the DefinitionId for the main Token of the node. */ + Id: string; + + /** The kind of node */ + Kind: "assembly" | "namespace" | "class" | "delegate" | "enum" | "interface" | "method" | "package" | "struct" | "type"; + + /** Tokens which are rendered after all child nodes. Depending on the language this would include the closing curly brace and/or empty lines. */ + BottomTokens?: StructuredToken[]; + + /** The nodes immediate children. For a namespace this would be classes, for a class this would be the class constructors and methods. Children are rendered after TopTokens but before BottomTokens, and are automatically indented.*/ + Children?: APITreeNode[]; + + /** Properties of the APITreeNode. */ + Properties?: APITreeNodeProperties; + + /** Tags of the APITreeNode. */ + Tags?: APITreeNodeTags[]; +} + +model StructuredToken { + /** Token Id. Previously known as DefinitionId. */ + Id: string; + + /** Represents the type of a structured token*/ + Kind: StructuredTokenKind; + + /** The token value which will be displayed. Spacing tokens (LineBreak, NonBreakingSpace, TabSpace, and ParameterSeparator) don't need to have value */ + Value?: string; + + /** Properties of the StructuredToken. */ + Properties?: StructuredTokenProperties; + + /** Tags of the StructuredToken. */ + Tags?: StructuredTokenTags[]; + + /** Classes used to render the StructuredTokens. */ + RenderClasses?: StructuredTokenRenderClasses[] +} + +model APITreeNodeProperties { + /** Use this only if you are looking to add a custom icon different from language wide defaults set by APITreeNode kind*/ + IconName?: string; +} + +model StructuredTokenProperties { + /** Group a sequence of consecutive StructuredTokens. doc indicates that the group of tokens is documentation. */ + GroupId?: "doc"; + + /** Id to navigate to when StructuredToken is clicked. */ + NavigateToId?: string; +} + +enum StructuredTokenKind { + /** Default kind */ + Content, + + /** Starts a new line */ + LineBreak, + + /** Single Space */ + NonBreakingSpace, + + /** Four spaces */ + TabSpace, + + /** Use this between method parameters. Depending on user setting this would result in a LineBreak or a LineBreak + TabSpace */ + ParameterSeparator +} + +/** Classes used to render the StructuredTokens. Extendable by contributing styles at https://github.com/Azure/azure-sdk-tools/blob/main/src/dotnet/APIView/ClientSPA/src/app/_components/code-panel/code-panel.component.scss */ +union StructuredTokenRenderClasses { + "comment", + "keyword", + "keyword", + "literal", + /** string literal */ + "sliteral", + /** member name */ + "mname", + /** type name */ + "tname", + /** punctuation */ + "punc", + "text", + string +} + +union APITreeNodeTags { + /** Mark a token as deprecated. */ + "Deprecated", + /** Mark a node as Hidden. */ + "Hidden", + /** Indicate that a node should be hidden from the page navigation. */ + "HideFromNav", + /** Indicate that a node should not be used in computation of diff. */ + "SkipDiff", + /** The cross language definitionId for the node. */ + "CrossLangDefId" +} + +union StructuredTokenTags { + /** Mark a token as deprecated */ + "Deprecated", + /** Indicate that a Token should not be used in computing diff*/ + "SkipDiff", +} + +enum CodeDiagnosticLevel { + Default, + Info, + Warning, + Error, + Fatal +} \ No newline at end of file