Adds comments to all exported members

Author: bf-tomnomnom

cmd/jsluice/testdata/escapes.js

@@ -0,0 +1 @@
+let str = 'Hello,\x20World!'

cmd/jsluice/testdata/object.js

@@ -0,0 +1,10 @@
+const config = {
+    stage: false,
+    server: "example.com",
+    ttl: 3600,
+    dns: ["1.1.1.1", "8.8.8.8"],
+    paths: {
+        "home": "/",
+        "blog": "/blog"
+    }
+}

secret-matchers.go

@@ -4,9 +4,8 @@ import (
 	"strings"
 )
 
-// A Secret represents any bit of secret or otherwise interesting
-// data found within a JavaScript file. E.g. an AWS access key and
-// secret.
+// A Secret represents any secret or otherwise interesting data
+// found within a JavaScript file. E.g. an AWS access key.
 type Secret struct {
 	Kind     string            `json:"kind"`
 	Data     any               `json:"data"`
@@ -15,6 +14,7 @@ type Secret struct {
 	Context  map[string]string `json:"context"`
 }
 
+// Severity indicates how serious a finding is
 type Severity string
 
 const (

strings.go

@@ -180,8 +180,7 @@ func (s *stringLexer) String() string {
 }
 
 // DecodeString accepts a raw string as it might be found in some
-// JavaScript source code (without surrounding quotes), and converts
-// any escape sequences. E.g.
+// JavaScript source code, and converts any escape sequences. E.g:
 //   foo\x3dbar -> foo=bar // Hex escapes
 //   foo\u003Dbar -> foo=bar // Unicode escapes
 //   foo\u{003D}bar -> foo=bar // Braced unicode escapes

tree.go

@@ -9,59 +9,89 @@ import (
 	"github.com/smacker/go-tree-sitter/javascript"
 )
 
+// ExpressionPlaceholder is the string used to replace any
+// expressions when string concatenations are collapsed. E.g:
+//   "prefix" + someVar + "suffix"
+// Would become:
+//   prefixEXPRsuffix
 var ExpressionPlaceholder = "EXPR"
 
+// Node is a wrapper around a tree-sitter node. It serves as
+// an attachment point for convenience methods, and also to
+// store the raw JavaScript source that is a required argument
+// for many tree-sitter functions.
 type Node struct {
 	node   *sitter.Node
 	source []byte
 }
 
+// NewNode creates a new Node for the provided tree-sitter
+// node and a byte-slice containing the JavaScript source.
+// The source provided should be the complete source code
+// and not just the source for the node in question.
 func NewNode(n *sitter.Node, source []byte) *Node {
 	return &Node{
 		node:   n,
 		source: source,
 	}
 }
 
+// AsObject returns a Node as jsluice's internal object type,
+// to allow the fetching of keys etc
 func (n *Node) AsObject() object {
 	return newObject(n, n.source)
 }
 
+// Content returns the source code for a particular node.
 func (n *Node) Content() string {
 	if n.node == nil {
 		return ""
 	}
 	return n.node.Content(n.source)
 }
 
+// Type returns the tree-sitter type string for a Node.
+// E.g. string, object, call_expression. If the node is
+// nil then an empty string is returned.
 func (n *Node) Type() string {
 	if n.node == nil {
 		return ""
 	}
 	return n.node.Type()
 }
 
+// Fetches a child Node from a named field. For example,
+// the 'pair' node has two fields: key, and value.
 func (n *Node) ChildByFieldName(name string) *Node {
 	if !n.IsValid() {
 		return nil
 	}
 	return NewNode(n.node.ChildByFieldName(name), n.source)
 }
 
+// NamedChild returns the 'named' child Node at the provided
+// index. Tree-sitter considers a child to be named if it has
+// a name in the syntax tree. Things like brackets are not named,
+// but things like variables and function calls are named.
+// See https://tree-sitter.github.io/tree-sitter/using-parsers#named-vs-anonymous-nodes
+// for more details.
 func (n *Node) NamedChild(index int) *Node {
 	if !n.IsValid() {
 		return nil
 	}
 	return NewNode(n.node.NamedChild(index), n.source)
 }
 
+// NamedChildCount returns the number of named children a Node has.
 func (n *Node) NamedChildCount() int {
 	if !n.IsValid() {
 		return 0
 	}
 	return int(n.node.NamedChildCount())
 }
 
+// NamedChildren returns a slice of *Node containg all
+// named children for a node.
 func (n *Node) NamedChildren() []*Node {
 	count := n.NamedChildCount()
 	out := make([]*Node, 0, count)
@@ -83,6 +113,7 @@ func (n *Node) NamedChildren() []*Node {
 //
 //  ./upload.php?profile=EXPR&show=EXPR
 //
+// The value of ExpressionPlaceholder is used as a placeholder, defaulting to 'EXPR'
 func (n *Node) CollapsedString() string {
 	if !n.IsValid() {
 		return ""
@@ -101,18 +132,39 @@ func (n *Node) CollapsedString() string {
 	}
 }
 
+// IsValid returns true if the *Node and the underlying
+// tree-sitter node are both not nil.
 func (n *Node) IsValid() bool {
 	return n != nil && n.node != nil
 }
 
+// RawString returns the raw JavaScript representation
+// of a string (i.e. escape sequences are left undecoded)
+// but with the surrounding quotes removed.
 func (n *Node) RawString() string {
 	return dequote(n.Content())
 }
 
+// DecodedString returns a fully decoded version of a
+// JavaScript string. It is just a convenience wrapper
+// around the DecodeString function.
 func (n *Node) DecodedString() string {
 	return DecodeString(n.Content())
 }
 
+// AsGoType returns a representation of a Node as a native
+// Go type, defaulting to a string containing the JavaScript
+// source for the Node. Return types are:
+//
+//   string => string
+//   number => int, float64
+//   object => map[string]any
+//   array  => []any
+//   false  => false
+//   true   => true
+//   null   => nil
+//   other  => string
+//
 func (n *Node) AsGoType() any {
 	if n == nil {
 		return nil
@@ -138,6 +190,7 @@ func (n *Node) AsGoType() any {
 	}
 }
 
+// AsMap returns a representation of the Node as a map[string]any
 func (n *Node) AsMap() map[string]any {
 	if n.Type() != "object" {
 		return map[string]any{}
@@ -160,6 +213,7 @@ func (n *Node) AsMap() map[string]any {
 	return out
 }
 
+// AsArray returns a representation of the Node as a []any
 func (n *Node) AsArray() []any {
 	if n.Type() != "array" {
 		return []any{}
@@ -176,6 +230,9 @@ func (n *Node) AsArray() []any {
 	return out
 }
 
+// AsNumber returns a representation of the Node as an int or float64.
+//
+// Note: hex, octal etc number formats are currently unsupported
 func (n *Node) AsNumber() any {
 	if n.Type() != "number" {
 		return 0
@@ -201,13 +258,20 @@ func (n *Node) AsNumber() any {
 	return i
 }
 
+// Parent returns the Parent Node for a Node
 func (n *Node) Parent() *Node {
 	if !n.IsValid() {
 		return nil
 	}
 	return NewNode(n.node.Parent(), n.source)
 }
 
+// Query executes a tree-sitter query on a specific Node.
+// Nodes matching the query are passed one at a time to the
+// provided callback function.
+//
+// See https://tree-sitter.github.io/tree-sitter/using-parsers#pattern-matching-with-queries
+// for query syntax documentation.
 func (n *Node) Query(query string, fn func(*Node)) {
 	if !n.IsValid() {
 		return
@@ -237,6 +301,9 @@ func (n *Node) Query(query string, fn func(*Node)) {
 	}
 }
 
+// IsStringy returns true if a Node is a string
+// or is an expression starting with a string
+// (e.g. a string concatenation expression).
 func (n *Node) IsStringy() bool {
 	if n.Type() == "string" {
 		return true
@@ -255,17 +322,22 @@ func (n *Node) IsStringy() bool {
 	}
 }
 
+// dequote removes surround quotes from the provided string
 func dequote(in string) string {
 	return strings.Trim(in, "'\"`")
 }
 
+// content returns the source for the provided tree-sitter
+// node, checking if the node is nil first.
 func content(n *sitter.Node, source []byte) string {
 	if n == nil {
 		return ""
 	}
 	return n.Content(source)
 }
 
+// PrintTree returns a string representation of the syntax tree
+// for the provided JavaScript source
 func PrintTree(source []byte) string {
 	parser := sitter.NewParser()
 	parser.SetLanguage(javascript.GetLanguage())
@@ -276,6 +348,7 @@ func PrintTree(source []byte) string {
 	return getTree(root, source)
 }
 
+// getTree does the actual heavy lifting and recursion for PrintTree
 // TODO: provide a way to print the tree as a JSON object?
 func getTree(n *sitter.Node, source []byte) string {
 

user-patterns.go

@@ -7,6 +7,10 @@ import (
 	"regexp"
 )
 
+// A UserPattern represents a pattern that was provided by a
+// when using the command-line tool. When using the package
+// directly, a SecretMatcher can be created directly instead
+// of creating a UserPattern
 type UserPattern struct {
 	Name     string   `json:"name"`
 	Key      string   `json:"key"`
@@ -19,6 +23,8 @@ type UserPattern struct {
 	reValue *regexp.Regexp
 }
 
+// ParseRegex parses all of the user-provided regular expressions
+// for a pattern into Go *regexp.Regexp types
 func (u *UserPattern) ParseRegex() error {
 	if u.Value != "" {
 		re, err := regexp.Compile(u.Value)
@@ -53,20 +59,26 @@ func (u *UserPattern) ParseRegex() error {
 	return nil
 }
 
+// MatchValue returns true if a pattern's value regex matches
+// the supplied value, or if there is no value regex.
 func (u *UserPattern) MatchValue(in string) bool {
 	if u.reValue == nil {
 		return true
 	}
 	return u.reValue.MatchString(in)
 }
 
+// MatchKey returns true if a pattern's key regex matches
+// the supplied value, or if there is no key regex
 func (u *UserPattern) MatchKey(in string) bool {
 	if u.reKey == nil {
 		return true
 	}
 	return u.reKey.MatchString(in)
 }
 
+// SecretMatcher returns a SecretMatcher based on the UserPattern,
+// for use with (*Analyzer).AddSecretMatcher()
 func (u *UserPattern) SecretMatcher() SecretMatcher {
 	if len(u.Object) > 0 {
 		return u.objectMatcher()
@@ -79,6 +91,7 @@ func (u *UserPattern) SecretMatcher() SecretMatcher {
 	return u.stringMatcher()
 }
 
+// objectMatcher returns a SecretMatcher for matching against objects
 func (u *UserPattern) objectMatcher() SecretMatcher {
 	return SecretMatcher{"(object) @matches", func(n *Node) *Secret {
 		pairs := n.NamedChildren()
@@ -110,6 +123,7 @@ func (u *UserPattern) objectMatcher() SecretMatcher {
 	}}
 }
 
+// pairMatcher returns a SecretMatcher for matching against key/value pairs
 func (u *UserPattern) pairMatcher() SecretMatcher {
 	return SecretMatcher{"(pair) @matches", func(n *Node) *Secret {
 
@@ -148,6 +162,7 @@ func (u *UserPattern) pairMatcher() SecretMatcher {
 	}}
 }
 
+// stringMatcher returns a SecretMatcher for matching against string literals
 func (u *UserPattern) stringMatcher() SecretMatcher {
 	return SecretMatcher{"(string) @matches", func(n *Node) *Secret {
 		in := n.RawString()
@@ -177,8 +192,11 @@ func (u *UserPattern) stringMatcher() SecretMatcher {
 	}}
 }
 
+// UserPatterns is an alias for a slice of *UserPattern
 type UserPatterns []*UserPattern
 
+// SecretMatchers returns a slice of SecretMatcher for use with
+// (*Analyzer).AddSecretMatchers()
 func (u UserPatterns) SecretMatchers() []SecretMatcher {
 	out := make([]SecretMatcher, 0)
 
@@ -188,6 +206,9 @@ func (u UserPatterns) SecretMatchers() []SecretMatcher {
 	return out
 }
 
+// ParseUserPatterns accepts an io.Reader pointing to a JSON user-pattern
+// definition file, and returns a list of UserPatterns, and any error that
+// occurred.
 func ParseUserPatterns(r io.Reader) (UserPatterns, error) {
 	out := make(UserPatterns, 0)