feat(arguments): support from to alias to another module's argument (#…

…129)

* feat(arguments): support from to alias to another module's argument

* add another, better, test

* docs update

* fix commands gen, update file.RemoveAll docs

* fix append issue

.prettierignore

@@ -3,5 +3,4 @@
 *.md
 
 ###Block(prettierignoreExtras)
-
 ###EndBlock(prettierignoreExtras)

docs/content/en/commands/stencil.md

@@ -19,24 +19,28 @@ USAGE:
    stencil [global options] command [command options] [arguments...]
 
 VERSION:
-   v1.15.1
+   v1.24.0
 
 DESCRIPTION:
    a smart templating engine for service development
 
 COMMANDS:
-   describe
-   create
+   describe  
+   create    
+   docs      
+   updater   Commands for interacting with the built-in updater
    help, h   Shows a list of commands or help for one command
 
 GLOBAL OPTIONS:
-   --dry-run, --dryrun   Don't write files to disk (default: false)
-   --frozen-lockfile     Use versions from the lockfile instead of the latest (default: false)
-   --skip-update         skips the updater check (default: false)
-   --debug               enables debug logging for all components (i.e updater) (default: false)
-   --enable-prereleases  Enable considering pre-releases when checking for updates (default: false)
-   --force-update-check  Force checking for an update (default: false)
-   --help, -h            show help (default: false)
-   --version, -v         print the version (default: false)
+   --dry-run, --dryrun             Don't write files to disk (default: false)
+   --frozen-lockfile               Use versions from the lockfile instead of the latest (default: false)
+   --use-prerelease                Use prerelease versions of stencil modules (default: false)
+   --allow-major-version-upgrades  Allow major version upgrades without confirmation (default: false)
+   --skip-update                   skips the updater check (default: false)
+   --debug                         enables debug logging for all components that use logrus (default: false)
+   --enable-prereleases            Enable considering pre-releases when checking for updates (default: false)
+   --force-update-check            Force checking for an update (default: false)
+   --help, -h                      show help (default: false)
+   --version, -v                   print the version (default: false)
 
 ```

docs/content/en/commands/stencil_create.md

@@ -22,11 +22,11 @@ DESCRIPTION:
    Commands to create template repositories, or stencil powered repositories
 
 COMMANDS:
-   module, templaterepository
+   module, templaterepository  
    help, h                     Shows a list of commands or help for one command
 
 OPTIONS:
    --help, -h  show help (default: false)
-
+   
 
 ```

docs/content/en/commands/stencil_create_module.md

@@ -13,7 +13,7 @@ menu:
 
 ```bash
 NAME:
-   stencil create module -
+   stencil create module - 
 
 USAGE:
    stencil create module [command options] create module <name>
@@ -24,6 +24,6 @@ DESCRIPTION:
 OPTIONS:
    --native-extension  Generates a native extension (default: false)
    --help, -h          show help (default: false)
-
+   
 
 ```

docs/content/en/commands/stencil_describe.md

@@ -13,7 +13,7 @@ menu:
 
 ```bash
 NAME:
-   stencil describe -
+   stencil describe - 
 
 USAGE:
    stencil describe [command options] [arguments...]
@@ -23,6 +23,6 @@ DESCRIPTION:
 
 OPTIONS:
    --help, -h  show help (default: false)
-
+   
 
 ```

docs/content/en/functions/file.Block.md

@@ -10,6 +10,7 @@ menu:
     parent: "functions"
 ---
 
+
 ```go-text-template
 ###Block(name)
 Hello, world!
@@ -27,3 +28,5 @@ Hello, world!
 {{ file.Block "name" }}
 ###EndBlock(name)
 ```
+
+

docs/content/en/functions/file.Create.md

@@ -10,8 +10,10 @@ menu:
     parent: "functions"
 ---
 
+
 If the template has a single file with no contents this file replaces it\.
 
+
 ```go-text-template
 {{- define "command" }}
 package main
@@ -30,3 +32,5 @@ func main() {
 {{- stencil.ApplyTemplate "command" | file.SetContents }}
 {{- end }}
 ```
+
+

docs/content/en/functions/file.Delete.md

@@ -10,6 +10,9 @@ menu:
     parent: "functions"
 ---
 
+
 ```go-text-template
 {{ file.Delete }}
 ```
+
+

docs/content/en/functions/file.Path.md

@@ -10,6 +10,9 @@ menu:
     parent: "functions"
 ---
 
+
 ```go-text-template
 {{ file.Path }}
 ```
+
+

docs/content/en/functions/file.SetContents.md

@@ -10,8 +10,12 @@ menu:
     parent: "functions"
 ---
 
+
 This is useful for programmatic file generation within a template\.
 
+
 ```go-text-template
 {{ file.SetContents "Hello, world!" }}
 ```
+
+

docs/content/en/functions/file.SetPath.md

@@ -10,8 +10,12 @@ menu:
     parent: "functions"
 ---
 
+
 ```go-text-template
 {{ $_ := file.SetPath "new/path/to/file.txt" }}
 ```
 
+
 Note: The $\_ is required to ensure \<nil\> isn't outputted into the template\.
+
+

docs/content/en/functions/file.Skip.md

@@ -10,6 +10,9 @@ menu:
     parent: "functions"
 ---
 
+
 ```go-text-template
 {{ $_ := file.Skip "A reason to skip this reason" }}
 ```
+
+

docs/content/en/functions/file.Static.md

@@ -10,8 +10,12 @@ menu:
     parent: "functions"
 ---
 
+
 Marking a file is equivalent to calling file\.Skip\, but instead file\.Skip is only called if the file already exists\. This is useful for files you want to generate but only once\. It's generally recommended that you do not do this as it limits your ability to change the file in the future\.
 
+
 ```go-text-template
 {{ $_ := file.Static }}
 ```
+
+

docs/content/en/functions/stencil.AddToModuleHook.md

@@ -10,9 +10,13 @@ menu:
     parent: "functions"
 ---
 
+
 This functions write to module hook owned by another module for it to operate on\. These are not strongly typed so it's best practice to look at how the owning module uses it for now\. Module hooks must always be written to with a list to ensure that they can always be written to multiple times\.
 
+
 ```go-text-template
 {{- /* This writes to a module hook */}}
 {{ stencil.AddToModuleHook "github.com/myorg/repo" "myModuleHook" (list "myData") }}
 ```
+
+

docs/content/en/functions/stencil.ApplyTemplate.md

@@ -10,8 +10,10 @@ menu:
     parent: "functions"
 ---
 
+
 This function does not support rendering a template from another module\.
 
+
 ```go-text-template
 {{- define "command"}}
 package main
@@ -26,3 +28,5 @@ func main() {
 
 {{- stencil.ApplyTemplate "command" | file.SetContents }}
 ```
+
+

docs/content/en/functions/stencil.Arg.md

@@ -10,6 +10,12 @@ menu:
     parent: "functions"
 ---
 
+
 ```go-text-template
 {{- stencil.Arg "name" }}
 ```
+
+
+Note: Using \`stencil\.Arg\` with no path returns all arguments and is equivalent to \`stencil\.Args\`\. However\, that is DEPRECATED along with \`stencil\.Args\` as it doesn't provide default types\, or check the JSON schema\, or track which module calls what argument\.
+
+

docs/content/en/functions/stencil.Args.md

@@ -2,16 +2,25 @@
 title: stencil.Args
 linktitle: stencil.Args
 description: >
-  Args returns all arguments passed to stencil from the service's manifest
+  
 date: 2022-05-18
 categories: [functions]
 menu:
   docs:
     parent: "functions"
 ---
 
+Deprecated: Use Arg instead\. Args returns all arguments passed to stencil from the service's manifest
+
+
 Note: This doesn't set default values and is instead representative of \_all\_ data passed in its raw form\.
 
+
+This is deprecated and will be removed in a future release\.
+
+
 ```go-text-template
 {{- (stencil.Args).name }}
 ```
+
+

docs/content/en/functions/stencil.GetModuleHook.md

@@ -10,12 +10,16 @@ menu:
     parent: "functions"
 ---
 
+
 This is incredibly useful for allowing other modules to write to files that your module owns\. Think of them as extension points for your module\. The value returned by this function is always a \[\]interface\{\}\, aka a list\.
 
+
 ```go-text-template
 {{- /* This returns a []interface{} */}}
 {{ $hook := stencil.GetModuleHook "myModuleHook" }}
 {{- range $hook }}
   {{ . }}
 {{- end }}
 ```
+
+

docs/content/en/functions/stencil.ReadFile.md

@@ -10,6 +10,9 @@ menu:
     parent: "functions"
 ---
 
+
 ```go-text-template
 {{ stencil.ReadFile "myfile.txt" }}
 ```
+
+

docs/content/en/reference/template-module.md

@@ -55,6 +55,7 @@ The important keys that a module has are listed below, but an exhaustive list ca
   - `schema` - a JSON schema for the argument
   - `required` - whether or not the argument is required to be set
   - `default` - a default value for the argument, cannot be set when required is true
+  - `from` - aliases this argument to another module's argument. Only supports one-level deep.
 
 #### Writing a JSON Schema
 
@@ -81,6 +82,29 @@ items:
 	type: string
 ```
 
+#### Aliasing an argument with `from`
+
+Aliasing an argument allows you to reference another argument from within the module. For example, if you have an argument called `description` and you want to alias it to another argument called from the module `github.com/getoutreach/stencil-base`, you can do so like so:
+
+```yaml
+# your module
+arguments:
+	description:
+		from: github.com/getoutreach/stencil-base
+
+# github.com/getoutreach/stencil-base
+arguments:
+	description:
+		schema:
+			type: string
+```
+
+There's a few limitations with aliasing arguments:
+
+ * Aliasing an argument to another argument that is itself aliased is not allowed.
+ * When `from` is used, no other properties on the argument being aliased can be set.
+ * When aliasing to a module, that module _must_ be listed in the `modules` key of the module aliasing the argument.
+
 ## Module Hooks
 
 Module hooks enable other modules to write to a section of a file in your module. This can be done with the [`stencil.GetModuleHook "name"`](/stencil/functions/stencil.getmodulehook) function. This returns a `[]interface{}`, or for non-gophers a list of any type. You can process this with a `range` or in any other method you'd like to generate whatever you need for your DSL.

docs/gen/commands/main.go

@@ -8,7 +8,6 @@ package main
 import (
 	"bytes"
 	"fmt"
-	"io/ioutil"
 	"os"
 	"os/exec"
 	"path/filepath"
@@ -74,17 +73,18 @@ func generateMarkdown() ([]file, error) {
 			}
 
 			if parsingCommands {
-
 				//   describe, d -> describe
-				command := strings.TrimSpace(strings.Split(line, ",")[0])
+				command := strings.Split(strings.TrimSpace(strings.Split(line, ",")[0]), " ")[0]
 
 				// skip the help command because it results in duplicates
 				if command == "help" {
 					continue
 				}
 
 				// args + new command
-				newArgs := append(args, command)
+				newArgs := make([]string, len(args)+1)
+				copy(newArgs, args)
+				newArgs[len(newArgs)-1] = command
 				fmt.Println("Discovered command:", strings.Join(newArgs, " "))
 				commands = append(commands, newArgs)
 			}
@@ -126,7 +126,7 @@ func generateMarkdown() ([]file, error) {
 // saveMarkdown writes the markdown files to disk.
 func saveMarkdown(files []file) error {
 	for _, f := range files {
-		if err := ioutil.WriteFile(filepath.Join("content", "en", "commands", f.Name+".md"), []byte(f.Contents), 0644); err != nil {
+		if err := os.WriteFile(filepath.Join("content", "en", "commands", f.Name+".md"), []byte(f.Contents), 0644); err != nil {
 			return err
 		}
 	}

docs/gen/functions/main.go

@@ -8,7 +8,6 @@ package main
 import (
 	"fmt"
 	"go/build"
-	"io/ioutil"
 	"os"
 	"path/filepath"
 	"strings"
@@ -78,7 +77,7 @@ func generateMarkdown() ([]file, error) {
 // saveMarkdown writes the markdown files to disk.
 func saveMarkdown(files []file) error {
 	for _, f := range files {
-		if err := ioutil.WriteFile(filepath.Join("content", "en", "functions", f.Name+".md"), []byte(f.Contents), 0644); err != nil {
+		if err := os.WriteFile(filepath.Join("content", "en", "functions", f.Name+".md"), []byte(f.Contents), 0644); err != nil {
 			return err
 		}
 	}

internal/codegen/stencil_test.go

@@ -69,11 +69,11 @@ func TestModuleHookRender(t *testing.T) {
 	ctx := context.Background()
 
 	// create modules
-	m1, err := modulestest.NewModuleFromTemplates(nil, "testing1", "testdata/module-hook/m1.tpl")
+	m1, err := modulestest.NewModuleFromTemplates(nil, "testing1", nil, "testdata/module-hook/m1.tpl")
 	if err != nil {
 		t.Errorf("failed to create module 1: %v", err)
 	}
-	m2, err := modulestest.NewModuleFromTemplates(nil, "testing2", "testdata/module-hook/m2.tpl")
+	m2, err := modulestest.NewModuleFromTemplates(nil, "testing2", nil, "testdata/module-hook/m2.tpl")
 	if err != nil {
 		t.Errorf("failed to create module 2: %v", err)
 	}