DOCS: TypeScript updates (#2402)

build/generate/dtsFile.go

@@ -1,10 +1,14 @@
 package main
 
 import (
+	"fmt"
 	"os"
+	"path"
 	"strings"
 )
 
+var commentStart = "@dnscontrol-auto-doc-comment "
+
 func generateDTSFile(funcs string) error {
 	names := []string{
 		"base-types",
@@ -20,9 +24,50 @@ func generateDTSFile(funcs string) error {
 		if err != nil {
 			return err
 		}
+		// Find all instances of `/** @dnscontrol-auto-doc-comment <path> */`
+		// and replace them with the contents of the file at <path>.
+		// This allows us to keep the documentation in the same file as the code.
+		for {
+			start := strings.Index(string(content), commentStart)
+			if start == -1 {
+				break
+			}
+			end := strings.Index(string(content[start:]), "\n")
+			if end == -1 {
+				return fmt.Errorf("unterminated @dnscontrol-auto-doc-comment in '%s'", name)
+			}
+
+			docPath := string(content[start+len(commentStart) : start+end])
+			println("Replacing", docPath)
+
+			if strings.Contains(docPath, "..") {
+				return fmt.Errorf("invalid path '%s' in '%s'", docPath, name)
+			}
+
+			newPath := path.Clean(join("documentation", docPath))
+			if !strings.HasPrefix(newPath, "documentation") {
+				return fmt.Errorf("invalid path '%s' in '%s'", docPath, name)
+			}
+			_, body, err := readDocFile(newPath)
+			if err != nil {
+				return err
+			}
+
+			body = strings.ReplaceAll(strings.Trim(body, "\n"), "\n", "\n * ")
+
+			content = append(content[:start], append([]byte(body), content[start+end:]...)...)
+		}
+
 		combined = append(combined, string(content))
 	}
 	combined = append(combined, funcs)
-	os.WriteFile(join("commands", "types", "dnscontrol.d.ts"), []byte(strings.Join(combined, "\n\n")), 0644)
+	fileContent := strings.Join(combined, "\n\n")
+	lines := strings.Split(fileContent, "\n")
+	fileContent = ""
+	for _, line := range lines {
+		fileContent += strings.TrimRight(line, " \t") + "\n"
+	}
+	fileContent = strings.TrimRight(fileContent, "\n")
+	os.WriteFile(join("commands", "types", "dnscontrol.d.ts"), []byte(fileContent+"\n"), 0644)
 	return nil
 }

build/generate/functionTypes.go

@@ -16,6 +16,7 @@ func join(parts ...string) string {
 	return strings.Join(parts, string(os.PathSeparator))
 }
 
+// removes repeated blank lines, replacing them with a single blank line.
 func fixRuns(s string) string {
 	lines := strings.Split(s, "\n")
 	var out []string
@@ -32,6 +33,33 @@ func fixRuns(s string) string {
 
 var delimiterRegex = regexp.MustCompile(`(?m)^---\n`)
 
+func readDocFile(fPath string) (map[string]interface{}, string, error) {
+	content, err := os.ReadFile(fPath)
+	if err != nil {
+		return nil, "", err
+	}
+	frontMatter, body, err := parseFrontMatter(string(content))
+	if err != nil {
+		return nil, "", err
+	}
+
+	lines := strings.Split(body, "\n")
+
+	body = ""
+
+	for _, line := range lines {
+		if strings.HasPrefix(line, "{%") && strings.HasSuffix(line, "%}") {
+			continue
+		}
+		body += line + "\n"
+	}
+
+	body = strings.ReplaceAll(body, "**NOTE**", "NOTE")
+	body = strings.ReplaceAll(body, "**WARNING**", "WARNING")
+	body = fixRuns(body)
+	return frontMatter, body, nil
+}
+
 func parseFrontMatter(content string) (map[string]interface{}, string, error) {
 	delimiterIndices := delimiterRegex.FindAllStringIndex(content, 2)
 	if len(delimiterIndices) < 1 {
@@ -93,32 +121,16 @@ func generateFunctionTypes() (string, error) {
 				return "", errors.New("not a file: " + fPath)
 			}
 			// println("Processing", fPath)
-			content, err := os.ReadFile(fPath)
-			if err != nil {
-				return "", err
-			}
-			frontMatter, body, err := parseFrontMatter(string(content))
+			frontMatter, body, err := readDocFile(fPath)
 			if err != nil {
 				println("Error parsing front matter in", fPath, "error: ", err.Error())
 				continue
+
 			}
 			if frontMatter["ts_ignore"] == true {
 				continue
 			}
 
-			lines := strings.Split(body, "\n")
-			body = ""
-			for _, line := range lines {
-				if strings.HasPrefix(line, "{%") && strings.HasSuffix(line, "%}") {
-					continue
-				}
-				body += line + "\n"
-			}
-
-			body = strings.ReplaceAll(body, "**NOTE**", "NOTE")
-			body = strings.ReplaceAll(body, "**WARNING**", "WARNING")
-			body = fixRuns(body)
-
 			paramNames := []string{}
 			if frontMatter["parameters"] != nil {
 				for _, p := range frontMatter["parameters"].([]interface{}) {

commands/types/dnscontrol.d.ts

@@ -37,7 +37,7 @@ type Duration =
 /**
  * `FETCH` is a wrapper for the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API). This allows dynamically setting DNS records based on an external data source, e.g. the API of your cloud provider.
  *
- * Compared to `fetch` from Fetch API, `FETCH` will call [PANIC](https://dnscontrol.org/js#PANIC) to terminate the execution of the script, and therefore DNSControl, if a network error occurs.
+ * Compared to `fetch` from Fetch API, `FETCH` will call [PANIC](PANIC.md) to terminate the execution of the script, and therefore DNSControl, if a network error occurs.
  *
  * Otherwise the syntax of `FETCH` is the same as `fetch`.
  *
@@ -48,15 +48,15 @@ type Duration =
  * > 1. Relying on external sources adds a point of failure. If the external source doesn't work, your script won't either. Please make sure you are aware of the consequences.
  * > 2. Make sure DNSControl only uses verified configuration if you want to use `FETCH`. For example, an attacker can send Pull Requests to your config repo, and have your CI test malicious configurations and make arbitrary HTTP requests. Therefore, `FETCH` must be explicitly enabled with flag `--allow-fetch` on DNSControl invocation.
  *
- * ```js
- * var REG_NONE = NewRegistrar('none');
- * var DNS_BIND = NewDnsProvider('bind');
+ * ```javascript
+ * var REG_NONE = NewRegistrar("none");
+ * var DNS_BIND = NewDnsProvider("bind");
  *
- * D('example.com', REG_NONE, DnsProvider(DNS_BIND), [
- *   A('@', '1.2.3.4'),
+ * D("example.com", REG_NONE, DnsProvider(DNS_BIND), [
+ *   A("@", "1.2.3.4"),
  * ]);
  *
- * FETCH('https://example.com', {
+ * FETCH("https://example.com", {
  *   // All three options below are optional
  *   headers: {"X-Authentication": "barfoo"},
  *   method: "POST",
@@ -65,8 +65,8 @@ type Duration =
  *   return r.text();
  * }).then(function(t) {
  *   // Example of generating record based on response
- *   D_EXTEND('example.com', [
- *     TXT('@', t.slice(0, 100)),
+ *   D_EXTEND("example.com", [
+ *     TXT("@", t.slice(0, 100)),
  *   ]);
  * });
  * ```
@@ -123,6 +123,7 @@ declare function require(name: string): true;
 declare const CAA_CRITICAL: RecordModifier;
 
 /**
+ * @deprecated
  * This disables a safety check intended to prevent:
  * 1. Two owners toggling a record between two settings.
  * 2. The other owner wiping all records at this label, which won't
@@ -835,7 +836,7 @@ declare function FRAME(name: string, target: string, ...modifiers: RecordModifie
  *
  * @see https://docs.dnscontrol.org/language-reference/domain-modifiers/ignore
  */
-declare const IGNORE: DomainModifier;
+declare function IGNORE(labelSpec: string, typeSpec?: string, targetSpec?: string): DomainModifier;
 
 /**
  * `IGNORE_NAME(a)` is the same as `IGNORE(a, "*", "*")`.
@@ -3099,4 +3100,3 @@ declare function SPF_BUILDER(opts: { label?: string; overflow?: string; overhead
  * @see https://docs.dnscontrol.org/language-reference/record-modifiers/ttl
  */
 declare function TTL(ttl: Duration): RecordModifier;
-

commands/types/fetch.d.ts

@@ -1,39 +1,5 @@
 /**
- * `FETCH` is a wrapper for the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API). This allows dynamically setting DNS records based on an external data source, e.g. the API of your cloud provider.
- *
- * Compared to `fetch` from Fetch API, `FETCH` will call [PANIC](https://dnscontrol.org/js#PANIC) to terminate the execution of the script, and therefore DNSControl, if a network error occurs.
- *
- * Otherwise the syntax of `FETCH` is the same as `fetch`.
- *
- * `FETCH` is not enabled by default. Please read the warnings below.
- *
- * > WARNING:
- * >
- * > 1. Relying on external sources adds a point of failure. If the external source doesn't work, your script won't either. Please make sure you are aware of the consequences.
- * > 2. Make sure DNSControl only uses verified configuration if you want to use `FETCH`. For example, an attacker can send Pull Requests to your config repo, and have your CI test malicious configurations and make arbitrary HTTP requests. Therefore, `FETCH` must be explicitly enabled with flag `--allow-fetch` on DNSControl invocation.
- *
- * ```js
- * var REG_NONE = NewRegistrar('none');
- * var DNS_BIND = NewDnsProvider('bind');
- *
- * D('example.com', REG_NONE, DnsProvider(DNS_BIND), [
- *   A('@', '1.2.3.4'),
- * ]);
- *
- * FETCH('https://example.com', {
- *   // All three options below are optional
- *   headers: {"X-Authentication": "barfoo"},
- *   method: "POST",
- *   body: "Hello World",
- * }).then(function(r) {
- *   return r.text();
- * }).then(function(t) {
- *   // Example of generating record based on response
- *   D_EXTEND('example.com', [
- *     TXT('@', t.slice(0, 100)),
- *   ]);
- * });
- * ```
+ * @dnscontrol-auto-doc-comment functions/global/FETCH.md
  */
 declare function FETCH(
     url: string,

commands/types/others.d.ts

@@ -9,6 +9,7 @@ declare function require(name: string): true;
 declare const CAA_CRITICAL: RecordModifier;
 
 /**
+ * @deprecated
  * This disables a safety check intended to prevent:
  * 1. Two owners toggling a record between two settings.
  * 2. The other owner wiping all records at this label, which won't

documentation/functions/domain/IGNORE.md

@@ -1,5 +1,13 @@
 ---
 name: IGNORE
+parameters:
+    - labelSpec
+    - typeSpec
+    - targetSpec
+parameter_types:
+    labelSpec: string
+    typeSpec: string?
+    targetSpec: string?
 ---
 
 `IGNORE()` makes it possible for DNSControl to share management of a domain