feat: Add SymbolRole for representing forward declarations (#217)

* feat: Add ForwardDeclaration SymbolRole

* fix: Format forward_declaration separately in snapshot logic

* test: Add forward decls to repro grammar + test case

* feat: Add lint rule for bad forward decls

* Rename forward declaration role -> forward definition

bindings/go/scip/convert.go

@@ -230,7 +230,7 @@ func (g *graph) emitDocument(index *Index, doc *Document) {
 		rangeIDs = append(rangeIDs, rangeID)
 		resultIDs := g.getOrInsertSymbolInformationIDs(occ.Symbol, localSymbolInformationTable)
 		g.emitEdge("next", reader.Edge{OutV: rangeID, InV: resultIDs.ResultSet})
-		isDefinition := occ.SymbolRoles&int32(SymbolRole_Definition) != 0
+		isDefinition := SymbolRole_Definition.Matches(occ)
 		if isDefinition && resultIDs.DefinitionResult > 0 {
 			g.emitEdge("item", reader.Edge{OutV: resultIDs.DefinitionResult, InVs: []int{rangeID}, Document: documentID})
 			symbolInfo, ok := documentSymbolTable[occ.Symbol]

bindings/go/scip/testutil/format.go

@@ -110,9 +110,11 @@ func FormatSnapshot(
 			}
 			b.WriteRune(' ')
 			role := "reference"
-			isDefinition := occ.SymbolRoles&int32(scip.SymbolRole_Definition) > 0
+			isDefinition := scip.SymbolRole_Definition.Matches(occ)
 			if isDefinition {
 				role = "definition"
+			} else if scip.SymbolRole_ForwardDefinition.Matches(occ) {
+				role = "forward_definition"
 			}
 			b.WriteString(role)
 			b.WriteRune(' ')

cmd/scip/lint.go

@@ -204,6 +204,9 @@ func (st *symbolTable) addOccurrence(path string, occ *scip.Occurrence) error {
 	if occ.Symbol == "" {
 		return emptyStringError{what: "symbol", context: fmt.Sprintf("occurrence at %s @ %s", path, scipRangeToString(*scip.NewRange(occ.Range)))}
 	}
+	if scip.SymbolRole_Definition.Matches(occ) && scip.SymbolRole_ForwardDefinition.Matches(occ) {
+		return forwardDefIsDefinitionError{occ.Symbol, path, *scip.NewRange(occ.Range)}
+	}
 	tryInsertOccurrence := func(occMap fileOccurrenceMap) error {
 		occKey := scipOccurrenceKey(occ)
 		if fileOccs, ok := occMap[path]; ok {
@@ -327,6 +330,17 @@ func (e missingSymbolForOccurrenceError) Error() string {
 		" in external symbols or any document", e.path, scipRangeToString(e.occ), e.symbol)
 }
 
+type forwardDefIsDefinitionError struct {
+	symbol string
+	path   string
+	range_ scip.Range
+}
+
+func (e forwardDefIsDefinitionError) Error() string {
+	return fmt.Sprintf("error: forward declaration for %v at %v @ %v was marked as definition",
+		e.symbol, e.path, scipRangeToString(e.range_))
+}
+
 type duplicateOccurrenceWarning struct {
 	symbol      string
 	path        string

cmd/scip/tests/reprolang/bindings/go/repro/ast.go

@@ -27,7 +27,8 @@ func (r *relationships) identifiers() []*identifier {
 }
 
 type referenceStatement struct {
-	name *identifier
+	name         *identifier
+	isForwardDef bool
 }
 
 type identifier struct {

cmd/scip/tests/reprolang/bindings/go/repro/parser.go

@@ -62,7 +62,8 @@ func (s *reproSourceFile) loadStatements() {
 			}
 		case "reference_statement":
 			s.references = append(s.references, &referenceStatement{
-				name: newIdentifier(s, child.ChildByFieldName("name")),
+				name:         newIdentifier(s, child.ChildByFieldName("name")),
+				isForwardDef: child.ChildByFieldName("forward_definition") != nil,
 			})
 		}
 	}

cmd/scip/tests/reprolang/bindings/go/repro/scip.go

@@ -63,7 +63,11 @@ func (s *reproSourceFile) occurrences() []*scip.Occurrence {
 		emit(rel.relations)
 	}
 	for _, ref := range s.references {
-		result = append(result, ref.name.occurrence(scip.SymbolRole_UnspecifiedSymbolRole))
+		role := scip.SymbolRole_UnspecifiedSymbolRole
+		if ref.isForwardDef {
+			role = scip.SymbolRole_ForwardDefinition
+		}
+		result = append(result, ref.name.occurrence(role))
 	}
 	return result
 }

cmd/scip/tests/reprolang/grammar.js

@@ -22,7 +22,12 @@ module.exports = grammar({
         field('name', $.identifier),
         field('roles', repeat($._definition_relations))
       ),
-    reference_statement: $ => seq('reference', field('name', $.identifier)),
+    reference_statement: $ =>
+      seq(
+        'reference',
+        field('forward_definition', optional('forward_definition')),
+        field('name', $.identifier)
+      ),
     _definition_relations: $ =>
       choice(
         $.implementation_relation,