diff --git a/samcli/commands/init/command.py b/samcli/commands/init/command.py index 8702b3f9a9..2806a96c72 100644 --- a/samcli/commands/init/command.py +++ b/samcli/commands/init/command.py @@ -106,6 +106,7 @@ def wrapped(*args, **kwargs): @click.command( "init", + help=HELP_TEXT, short_help=HELP_TEXT, context_settings={"max_content_width": 120}, cls=InitCommand, diff --git a/schema/samcli.json b/schema/samcli.json new file mode 100644 index 0000000000..cda45947bf --- /dev/null +++ b/schema/samcli.json @@ -0,0 +1,338 @@ +{ + "$schema": "http://json-schema.org/draft-04/schema", + "title": "AWS SAM CLI samconfig schema", + "type": "object", + "properties": { + "version": { + "title": "Config version", + "type": "number", + "default": 0.1 + } + }, + "required": [ + "version" + ], + "additionalProperties": false, + "patternProperties": { + "^.+$": { + "title": "Environment", + "properties": { + "init": { + "title": "Init command", + "description": "Initialize an AWS SAM application.", + "properties": { + "parameters": { + "title": "Parameters for the init command", + "description": "Available parameters for the init command:\n", + "type": "object", + "properties": {} + } + }, + "required": [ + "parameters" + ] + }, + "validate": { + "title": "Validate command", + "description": "Validate an AWS SAM Template.", + "properties": { + "parameters": { + "title": "Parameters for the validate command", + "description": "Available parameters for the validate command:\n", + "type": "object", + "properties": {} + } + }, + "required": [ + "parameters" + ] + }, + "build": { + "title": "Build command", + "description": "Build AWS serverless function code.", + "properties": { + "parameters": { + "title": "Parameters for the build command", + "description": "Available parameters for the build command:\n", + "type": "object", + "properties": {} + } + }, + "required": [ + "parameters" + ] + }, + "local_invoke": { + "title": "Local Invoke command", + "description": "Invoke AWS serverless functions locally.", + "properties": { + "parameters": { + "title": "Parameters for the local invoke command", + "description": "Available parameters for the local invoke command:\n", + "type": "object", + "properties": {} + } + }, + "required": [ + "parameters" + ] + }, + "local_start_api": { + "title": "Local Start Api command", + "description": "Run & test AWS serverless functions locally as a HTTP API.", + "properties": { + "parameters": { + "title": "Parameters for the local start api command", + "description": "Available parameters for the local start api command:\n", + "type": "object", + "properties": {} + } + }, + "required": [ + "parameters" + ] + }, + "local_generate_event": { + "title": "Local Generate Event command", + "description": "Generate events for Lambda functions.", + "properties": { + "parameters": { + "title": "Parameters for the local generate event command", + "description": "Available parameters for the local generate event command:\n", + "type": "object", + "properties": {} + } + }, + "required": [ + "parameters" + ] + }, + "local_start_lambda": { + "title": "Local Start Lambda command", + "description": "Emulate AWS serverless functions locally.", + "properties": { + "parameters": { + "title": "Parameters for the local start lambda command", + "description": "Available parameters for the local start lambda command:\n", + "type": "object", + "properties": {} + } + }, + "required": [ + "parameters" + ] + }, + "package": { + "title": "Package command", + "description": "Package an AWS SAM application.", + "properties": { + "parameters": { + "title": "Parameters for the package command", + "description": "Available parameters for the package command:\n", + "type": "object", + "properties": {} + } + }, + "required": [ + "parameters" + ] + }, + "deploy": { + "title": "Deploy command", + "description": "The sam deploy command creates a Cloudformation Stack and deploys your resources.", + "properties": { + "parameters": { + "title": "Parameters for the deploy command", + "description": "Available parameters for the deploy command:\n", + "type": "object", + "properties": {} + } + }, + "required": [ + "parameters" + ] + }, + "delete": { + "title": "Delete command", + "description": "The sam delete command deletes the CloudFormation\nstack and all the artifacts which were created using sam deploy.\n\n\ne.g. sam delete", + "properties": { + "parameters": { + "title": "Parameters for the delete command", + "description": "Available parameters for the delete command:\n", + "type": "object", + "properties": {} + } + }, + "required": [ + "parameters" + ] + }, + "logs": { + "title": "Logs command", + "description": "The sam logs commands fetches logs of Lambda Functions/CloudWatch log groups\nwith additional filtering by options.", + "properties": { + "parameters": { + "title": "Parameters for the logs command", + "description": "Available parameters for the logs command:\n", + "type": "object", + "properties": {} + } + }, + "required": [ + "parameters" + ] + }, + "publish": { + "title": "Publish command", + "description": "Use this command to publish a packaged AWS SAM template to\nthe AWS Serverless Application Repository to share within your team,\nacross your organization, or with the community at large.\n\n\nThis command expects the template's Metadata section to contain an\nAWS::ServerlessRepo::Application section with application metadata\nfor publishing. For more details on this metadata section, see\nhttps://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-template-publishing-applications.html\n\nExamples\n--------\nTo publish an application\n$ sam publish -t packaged.yaml --region ", + "properties": { + "parameters": { + "title": "Parameters for the publish command", + "description": "Available parameters for the publish command:\n", + "type": "object", + "properties": {} + } + }, + "required": [ + "parameters" + ] + }, + "traces": { + "title": "Traces command", + "description": "Use this command to fetch AWS X-Ray traces generated by your stack.\n\n\nRun the following command to fetch X-Ray traces by ID.\n$ sam traces --trace-id tracing-id-1 --trace-id tracing-id-2\n\nRun the following command to tail X-Ray traces as they become available.\n$ sam traces --tail", + "properties": { + "parameters": { + "title": "Parameters for the traces command", + "description": "Available parameters for the traces command:\n", + "type": "object", + "properties": {} + } + }, + "required": [ + "parameters" + ] + }, + "sync": { + "title": "Sync command", + "description": "NEW! Sync an AWS SAM Project to AWS.", + "properties": { + "parameters": { + "title": "Parameters for the sync command", + "description": "Available parameters for the sync command:\n", + "type": "object", + "properties": {} + } + }, + "required": [ + "parameters" + ] + }, + "pipeline_bootstrap": { + "title": "Pipeline Bootstrap command", + "description": "This command generates the required AWS infrastructure resources to connect to your CI/CD system.\nThis step must be run for each deployment stage in your pipeline, prior to running the sam pipline init command.", + "properties": { + "parameters": { + "title": "Parameters for the pipeline bootstrap command", + "description": "Available parameters for the pipeline bootstrap command:\n", + "type": "object", + "properties": {} + } + }, + "required": [ + "parameters" + ] + }, + "pipeline_init": { + "title": "Pipeline Init command", + "description": "This command generates a pipeline configuration file that your CI/CD system can use to deploy\nserverless applications using AWS SAM.\n\nBefore using sam pipeline init, you must bootstrap the necessary resources for each stage in your pipeline.\nYou can do this by running sam pipeline init --bootstrap to be guided through the setup and configuration\nfile generation process, or refer to resources you have previously created with the sam pipeline bootstrap command.", + "properties": { + "parameters": { + "title": "Parameters for the pipeline init command", + "description": "Available parameters for the pipeline init command:\n", + "type": "object", + "properties": {} + } + }, + "required": [ + "parameters" + ] + }, + "list_resources": { + "title": "List Resources command", + "description": "Get a list of resources that will be deployed to CloudFormation.\n\nIf a stack name is provided, the corresponding physical IDs of each\nresource will be mapped to the logical ID of each resource.", + "properties": { + "parameters": { + "title": "Parameters for the list resources command", + "description": "Available parameters for the list resources command:\n", + "type": "object", + "properties": {} + } + }, + "required": [ + "parameters" + ] + }, + "list_stack_outputs": { + "title": "List Stack Outputs command", + "description": "Get the stack outputs as defined in the SAM/CloudFormation template.", + "properties": { + "parameters": { + "title": "Parameters for the list stack outputs command", + "description": "Available parameters for the list stack outputs command:\n", + "type": "object", + "properties": {} + } + }, + "required": [ + "parameters" + ] + }, + "list_endpoints": { + "title": "List Endpoints command", + "description": "Get a summary of the cloud endpoints in the stack.\n\nThis command will show both the cloud and local endpoints that can\nbe used with sam local and sam sync. Currently the endpoint resources\nare Lambda functions and API Gateway API resources.", + "properties": { + "parameters": { + "title": "Parameters for the list endpoints command", + "description": "Available parameters for the list endpoints command:\n", + "type": "object", + "properties": {} + } + }, + "required": [ + "parameters" + ] + }, + "docs": { + "title": "Docs command", + "description": "NEW! Open the documentation in a browser.", + "properties": { + "parameters": { + "title": "Parameters for the docs command", + "description": "Available parameters for the docs command:\n* ", + "type": "object", + "properties": {} + } + }, + "required": [ + "parameters" + ] + }, + "remote_invoke": { + "title": "Remote Invoke command", + "description": "Invoke or send an event to resources in the cloud.", + "properties": { + "parameters": { + "title": "Parameters for the remote invoke command", + "description": "Available parameters for the remote invoke command:\n", + "type": "object", + "properties": {} + } + }, + "required": [ + "parameters" + ] + } + } + } + } +} \ No newline at end of file diff --git a/schema/schema.py b/schema/schema.py index 96c5beff67..9741f21db6 100644 --- a/schema/schema.py +++ b/schema/schema.py @@ -3,8 +3,9 @@ import importlib import json +from dataclasses import dataclass from enum import Enum -from typing import Any, Dict +from typing import Any, Dict, List, Optional import click @@ -13,13 +14,106 @@ class SchemaKeys(Enum): - SCHEMA_FILE_NAME = "samcli.json" + SCHEMA_FILE_NAME = "schema/samcli.json" SCHEMA_DRAFT = "http://json-schema.org/draft-04/schema" TITLE = "AWS SAM CLI samconfig schema" + ENVIRONMENT_REGEX = "^.+$" -def format_param(param: click.core.Option) -> Dict[str, Any]: - """Format a click Option parameter to a dictionary object. +@dataclass() +class SamCliParameterSchema: + """Representation of a parameter in the SAM CLI. + + It includes relevant information for the JSON schema, such as name, data type, + and description, among others. + """ + + name: str + type: str + description: str = "" + default: Optional[Any] = None + choices: Optional[Any] = None + + def to_schema(self) -> Dict[str, Any]: + """Return the JSON schema representation of the SAM CLI parameter.""" + param = {} + param.update({"title": self.name, "type": self.type, "description": self.description}) + if self.default: + param.update({"default": self.default}) + if self.choices: + param.update({"enum": self.choices}) + return param + + +@dataclass() +class SamCliCommandSchema: + """Representation of a command in the SAM CLI. + + It includes relevant information for the JSON schema, such as name, a description of the + command, and a list of all available parameters. + """ + + name: str # Full command name, with underscores (i.e. remote_invoke, local_start_lambda) + description: str + parameters: List[SamCliParameterSchema] + + def to_schema(self) -> dict: + """Return the JSON schema representation of the SAM CLI command.""" + COMMANDS_TO_EXCLUDE = [ # TEMPORARY: for use only while generating piece-by-piece + "deploy", + "build", + "local", + "validate", + "package", + "init", + "delete", + "bootstrap", + "list", + "traces", + "sync", + "publish", + "pipeline", + "logs", + "remote", + ] + split_cmd_name = self.name.split("_") + formatted_cmd_name = " ".join(split_cmd_name) + exclude_params = split_cmd_name[0] in COMMANDS_TO_EXCLUDE + formatted_params_list = ( + "* " + "\n* ".join([f"{param.name}:\n{param.description}" for param in self.parameters]) + if not exclude_params + else "" + ) + params_description = f"Available parameters for the {formatted_cmd_name} command:\n{formatted_params_list}" + + return { + self.name: { + "title": f"{formatted_cmd_name.title()} command", + "description": self.description or "", + "properties": { + "parameters": { + "title": f"Parameters for the {formatted_cmd_name} command", + "description": params_description, + "type": "object", + "properties": {param.name: param.to_schema() for param in self.parameters} + if not exclude_params + else {}, + }, + }, + "required": ["parameters"], + } + } + + +def clean_text(text: str) -> str: + """Clean up a string of text to be formatted for the JSON schema.""" + if not text: + return "" + return text.replace("\b", "").strip("\n").strip() + + +def format_param(param: click.core.Option) -> SamCliParameterSchema: + """Format a click Option parameter to a SamCliParameter object. A parameter object should contain the following information that will be necessary for including in the JSON schema: @@ -30,41 +124,41 @@ def format_param(param: click.core.Option) -> Dict[str, Any]: a list of those allowed options * default - The default option for that parameter """ - formatted_param: Dict[str, Any] = {"title": param.name, "description": param.help} - + param_type = param.type.name.lower() + formatted_param_type = "" # NOTE: Params do not have explicit "string" type; either "text" or "path". # All choice options are from a set of strings. - param_type = param.type.name.lower() if param_type in ["text", "path", "choice", "filename", "directory"]: - formatted_param["type"] = "string" + formatted_param_type = "string" elif param_type == "list": - formatted_param["type"] = "array" + formatted_param_type = "array" else: - formatted_param["type"] = param_type or "string" + formatted_param_type = param_type or "string" + + formatted_param: SamCliParameterSchema = SamCliParameterSchema( + param.name or "", formatted_param_type, clean_text(param.help or "") + ) if param.default: - formatted_param["default"] = list(param.default) if isinstance(param.default, tuple) else param.default + formatted_param.default = list(param.default) if isinstance(param.default, tuple) else param.default if param.type.name == "choice" and isinstance(param.type, click.Choice): - formatted_param["enum"] = list(param.type.choices) + formatted_param.choices = list(param.type.choices) return formatted_param -def get_params_from_command(cli, main_command_name: str = "") -> Dict[str, dict]: - """Given a command CLI, return it in a dictionary, pointing to its parameters as dictionary objects.""" - params = [ - param - for param in cli.params - if param.name and isinstance(param, click.core.Option) # exclude None and non-Options - ] - cmd_name = SamConfig.to_key([main_command_name, cli.name]) if main_command_name else cli.name - return {cmd_name: {param.name: format_param(param) for param in params}} +def get_params_from_command(cli) -> List[SamCliParameterSchema]: + """Given a CLI object, return a list of all parameters in that CLI, formatted as SamCliParameterSchema objects.""" + return [format_param(param) for param in cli.params if param.name and isinstance(param, click.core.Option)] -def retrieve_command_structure(package_name: str) -> Dict[str, dict]: +def retrieve_command_structure(package_name: str) -> List[SamCliCommandSchema]: """Given a SAM CLI package name, retrieve its structure. + Such a structure is the list of all subcommands as `SamCliCommandSchema`, which includes + the command's name, description, and its parameters. + Parameters ---------- package_name: str @@ -72,22 +166,32 @@ def retrieve_command_structure(package_name: str) -> Dict[str, dict]: Returns ------- - dict - A dictionary that maps the name of the command to its relevant click options. + List[SamCliCommandSchema] + A list of SamCliCommandSchema objects which represent either a command or a list of + subcommands within the package. """ module = importlib.import_module(package_name) - command = {} + command = [] if isinstance(module.cli, click.core.Group): # command has subcommands (e.g. local invoke) for subcommand in module.cli.commands.values(): - command.update( - get_params_from_command( - subcommand, - module.__name__.split(".")[-1], # if Group CLI, get last section of module name for cmd name + cmd_name = SamConfig.to_key([module.__name__.split(".")[-1], str(subcommand.name)]) + command.append( + SamCliCommandSchema( + cmd_name, + clean_text(subcommand.help or subcommand.short_help or ""), + get_params_from_command(subcommand), ) ) else: - command.update(get_params_from_command(module.cli)) + cmd_name = SamConfig.to_key([module.__name__.split(".")[-1]]) + command.append( + SamCliCommandSchema( + cmd_name, + clean_text(module.cli.help or module.cli.short_help or ""), + get_params_from_command(module.cli), + ) + ) return command @@ -100,8 +204,7 @@ def generate_schema() -> dict: A dictionary representation of the JSON schema. """ schema: dict = {} - commands = {} - params = set() # NOTE(leogama): Currently unused due to some params having different help values + commands: List[SamCliCommandSchema] = [] # Populate schema with relevant attributes schema["$schema"] = SchemaKeys.SCHEMA_DRAFT.value @@ -109,18 +212,17 @@ def generate_schema() -> dict: schema["type"] = "object" schema["properties"] = { # Version number required for samconfig files to be valid - "version": {"type": "number"} + "version": {"title": "Config version", "type": "number", "default": 0.1} } schema["required"] = ["version"] schema["additionalProperties"] = False # Iterate through packages for command and parameter information for package_name in _SAM_CLI_COMMAND_PACKAGES: - new_command = retrieve_command_structure(package_name) - commands.update(new_command) - for param_list in new_command.values(): - command_params = [param for param in param_list] - params.update(command_params) - # TODO: Generate schema for each of the commands + commands.extend(retrieve_command_structure(package_name)) + # Generate schema for each of the commands + schema["patternProperties"] = {SchemaKeys.ENVIRONMENT_REGEX.value: {"title": "Environment", "properties": {}}} + for command in commands: + schema["patternProperties"][SchemaKeys.ENVIRONMENT_REGEX.value]["properties"].update(command.to_schema()) return schema @@ -132,4 +234,4 @@ def write_schema(): if __name__ == "__main__": - generate_schema() + write_schema()