docs: Document local-id syntax (#206)

Author: varungandhi-src

.github/workflows/rust.yml

@@ -16,7 +16,7 @@ jobs:
       - uses: ./.github/actions/asdf
         with:
           rust: true
-      - run: cargo check
+      - run: cargo test
         working-directory: bindings/rust
       - run: cargo check
         working-directory: cmd/scip/tests/reprolang

bindings/go/scip/scip.pb.go

@@ -8,14 +8,42 @@ import (
 	"github.com/sourcegraph/sourcegraph/lib/errors"
 )
 
+// IsGlobalSymbol returns true if the symbol is obviously not a local symbol.
+//
+// CAUTION: Does not perform full validation of the symbol string's contents.
 func IsGlobalSymbol(symbol string) bool {
 	return !IsLocalSymbol(symbol)
 }
 
+// IsLocalSymbol returns true if the symbol is obviously not a global symbol.
+//
+// CAUTION: Does not perform full validation of the symbol string's contents.
 func IsLocalSymbol(symbol string) bool {
 	return strings.HasPrefix(symbol, "local ")
 }
 
+func isSimpleIdentifier(s string) bool {
+	for _, c := range s {
+		if ('0' <= c && c <= '9') || ('a' <= c && c <= 'z') || ('A' <= c && c <= 'Z') ||
+			c == '$' || c == '+' || c == '-' || c == '_' {
+			continue
+		}
+		return false
+	}
+	return true
+}
+
+func tryParseLocalSymbol(symbol string) (string, error) {
+	if !strings.HasPrefix(symbol, "local ") {
+		return "", nil
+	}
+	suffix := symbol[6:]
+	if len(suffix) > 0 && isSimpleIdentifier(suffix) {
+		return suffix, nil
+	}
+	return "", errors.Newf("expected format 'local <simple-identifier>' but got: %v", symbol)
+}
+
 // ParseSymbol parses an SCIP string into the Symbol message.
 func ParseSymbol(symbol string) (*Symbol, error) {
 	return ParsePartialSymbol(symbol, true)
@@ -24,14 +52,18 @@ func ParseSymbol(symbol string) (*Symbol, error) {
 // ParsePartialSymbol parses an SCIP string into the Symbol message
 // with the option to exclude the `.Descriptor` field.
 func ParsePartialSymbol(symbol string, includeDescriptors bool) (*Symbol, error) {
+	local, err := tryParseLocalSymbol(symbol)
+	if err != nil {
+		return nil, err
+	}
+	if local != "" {
+		return newLocalSymbol(local), nil
+	}
 	s := newSymbolParser(symbol)
 	scheme, err := s.acceptSpaceEscapedIdentifier("scheme")
 	if err != nil {
 		return nil, err
 	}
-	if scheme == "local" {
-		return newLocalSymbol(string(s.Symbol[s.index:])), nil
-	}
 	manager, err := s.acceptSpaceEscapedIdentifier("package manager")
 	if err != nil {
 		return nil, err

bindings/go/scip/symbol.go

@@ -82,11 +82,15 @@ func TestParseSymbol(t *testing.T) {
 	}
 }
 
-func TestParseSymbolNoCrash(t *testing.T) {
+func TestParseSymbolError(t *testing.T) {
 	for _, symbolName := range []string{
+		"",
 		"lsif-java maven package 1.0.0",
 		"lsif-java maven package 1.0.0 java/io/File#Entry.trailingstring",
 		"lsif-java maven package 1.0.0 java/io/File#Entry.unrecognizedSuffix@",
+		"local 🧠",
+		"local ",
+		"local &&&",
 	} {
 
 		if _, err := ParseSymbol(symbolName); err == nil {