Add scope-based parsing API for 10 RIDDL definition types

Enables parsing individual RIDDL files at specific scope levels
(Domain, Context, Entity, Epic, Streamlet, Module, Adaptor,
Projector, Repository, Saga) needed by Synapify visual editor.

- Add 10 parseAs* methods to TopLevelParser companion object
- Expose through RiddlLib (cross-platform) and RiddlAPI (JS facade)
- Add TypeScript type definitions with branded opaque types
- Remove include support from Function definitions
- Add 38 new test cases (17 parser-level + 21 RiddlLib-level)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: reid-spencer

language/jvm-native/src/test/scala/com/ossuminc/riddl/language/parsing/ScopedParsingTestJVM.scala

@@ -0,0 +1,11 @@
+/*
+ * Copyright 2019-2026 Ossum Inc.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package com.ossuminc.riddl.language.parsing
+
+import com.ossuminc.riddl.utils.{pc, ec}
+
+class ScopedParsingTestJVM extends ScopedParsingTest

language/shared/src/main/scala/com/ossuminc/riddl/language/AST.scala

@@ -778,8 +778,10 @@ object AST:
   /** Type of definitions that occur in a [[Function]] */
   private type OccursInFunction = OccursInVitalDefinition | Statement | Function
 
-  /** Type of definitions that occur in a [[Function]], with Include */
-  type FunctionContents = OccursInFunction | Include[OccursInFunction]
+  /** Type of definitions that occur in a [[Function]].
+    * Functions are self-contained and do not support includes.
+    */
+  type FunctionContents = OccursInFunction
 
   /** Type of definitions that occur in a [[Type]] */
   type TypeContents = Field | Method | Enumerator

language/shared/src/main/scala/com/ossuminc/riddl/language/parsing/EpicParser.scala

@@ -151,7 +151,7 @@ private[parsing] trait EpicParser {
     include[u, EpicContents]((p: P[?]) => epicDefinitions(using p.asInstanceOf[P[u]]))
   }
 
-  private def epicDefinitions[u: P]: P[Seq[EpicContents]] = {
+  private[parsing] def epicDefinitions[u: P]: P[Seq[EpicContents]] = {
     P(vitalDefinitionContents | useCase | shownBy | epicInclude).asInstanceOf[P[EpicContents]].rep(1)
   }
 

language/shared/src/main/scala/com/ossuminc/riddl/language/parsing/ExtensibleTopLevelParser.scala

@@ -174,6 +174,67 @@ trait ExtensibleTopLevelParser(using PlatformContext)
     }
   }
 
+  /** Parse the input as the contents of a Domain definition.
+    * Wraps the input in a synthetic `domain _scope_ is { ... }`
+    * and returns the resulting Domain.
+    */
+  def parseDomainContents: Either[Messages, Domain] =
+    doParse[Domain](p => domain(using p))
+
+  /** Parse the input as the contents of a Context definition.
+    * Wraps the input in a synthetic `context _scope_ is { ... }`
+    * and returns the resulting Context.
+    */
+  def parseContextContents: Either[Messages, Context] =
+    doParse[Context](p => context(using p))
+
+  /** Parse the input as the contents of an Entity definition.
+    * Wraps the input in a synthetic `entity _scope_ is { ... }`
+    * and returns the resulting Entity.
+    */
+  def parseEntityContents: Either[Messages, Entity] =
+    doParse[Entity](p => entity(using p))
+
+  /** Parse the input as the contents of a Module definition. */
+  def parseModuleContents: Either[Messages, Module] =
+    doParse[Module](p => module(using p))
+
+  /** Parse the input as the contents of an Adaptor definition. */
+  def parseAdaptorContents: Either[Messages, Adaptor] =
+    doParse[Adaptor](p => adaptor(using p))
+
+  /** Parse the input as the contents of a Projector definition. */
+  def parseProjectorContents: Either[Messages, Projector] =
+    doParse[Projector](p => projector(using p))
+
+  /** Parse the input as the contents of a Repository definition. */
+  def parseRepositoryContents: Either[Messages, Repository] =
+    doParse[Repository](p => repository(using p))
+
+  /** Parse the input as epic body content (use cases, types,
+    * etc.) and return a raw sequence of EpicContents.
+    */
+  def parseEpicDefinitions: Either[Messages, Seq[EpicContents]] =
+    doContentsParse[EpicContents](p => epicDefinitions(using p))
+      .map(_.toSeq)
+
+  /** Parse the input as saga body content (saga steps,
+    * inlets, outlets, functions) and return a raw sequence.
+    */
+  def parseSagaDefinitions: Either[Messages, Seq[SagaContents]] =
+    doContentsParse[SagaContents](p => sagaDefinitions(using p))
+      .map(_.toSeq)
+
+  /** Parse the input as streamlet processor content (handlers,
+    * types, functions, etc.) and return a raw sequence.
+    */
+  def parseStreamletDefinitions: Either[Messages, Seq[StreamletContents]] =
+    doContentsParse[StreamletContents] { (p: P[?]) =>
+      given P[Any] = p.asInstanceOf[P[Any]]
+      processorDefinitionContents(StatementsSet.StreamStatements)
+        .asInstanceOf[P[StreamletContents]].rep(1)
+    }.map(_.toSeq)
+
   def parseTokens: Either[Messages, List[Token]] = {
     parse[List[Token]](input, p => parseAllTokens(using p)) match
       case Left((messages, _)) => Left(messages)

language/shared/src/main/scala/com/ossuminc/riddl/language/parsing/FunctionParser.scala

@@ -15,10 +15,6 @@ import fastparse.MultiLineWhitespace.*
 private[parsing] trait FunctionParser {
   this: VitalDefinitionParser & StatementParser =>
 
-  private def functionInclude[u: P]: P[Include[FunctionContents]] = {
-    include[u, FunctionContents]((p: P[?]) => functionDefinitions(using p.asInstanceOf[P[u]]))
-  }
-
   def funcInput[u: P]: P[Aggregation] = {
     P(Keywords.requires ~ aggregation)./
   }
@@ -30,7 +26,7 @@ private[parsing] trait FunctionParser {
   private def functionDefinitions[u: P]: P[Seq[FunctionContents]] = {
     P(
       undefined(Seq.empty[FunctionContents]) | (
-        vitalDefinitionContents | function | functionInclude | statement(
+        vitalDefinitionContents | function | statement(
           StatementsSet.FunctionStatements
         )
       ).asInstanceOf[P[FunctionContents]]./.rep(0)
@@ -56,7 +52,6 @@ private[parsing] trait FunctionParser {
     P(
       Index ~ Keywords.function ~/ identifier ~ is ~ open ~/ functionBody ~ close ~ withMetaData ~/ Index
     )./.map { case (start, id, (ins, outs, contents), descriptives, end) =>
-      checkForDuplicateIncludes(contents)
       Function(at(start, end), id, ins, outs, contents.toContents, descriptives.toContents)
     }
   }

language/shared/src/main/scala/com/ossuminc/riddl/language/parsing/SagaParser.scala

@@ -29,7 +29,7 @@ private[parsing] trait SagaParser {
     include[u, SagaContents]((p: P[?]) => sagaDefinitions(using p.asInstanceOf[P[u]]))
   }
 
-  private def sagaDefinitions[u: P]: P[Seq[SagaContents]] = {
+  private[parsing] def sagaDefinitions[u: P]: P[Seq[SagaContents]] = {
     P(
       sagaStep | inlet | outlet | function | sagaInclude
     ).asInstanceOf[P[SagaContents]]./.rep(2)

language/shared/src/main/scala/com/ossuminc/riddl/language/parsing/TopLevelParser.scala

@@ -246,4 +246,235 @@ object TopLevelParser:
         Right(mapped)
     end match
   end mapTextAndToken
+
+  /** Parse content as if it were inside a Domain body.
+    *
+    * Wraps the input in a synthetic `domain SyntheticScope is { ... }`
+    * declaration, parses it, and returns the resulting Domain.
+    *
+    * @param input The RiddlParserInput containing domain-level content
+    * @param withVerboseFailures Enable verbose parse failure messages
+    * @return Either error messages or the parsed Domain
+    */
+  def parseAsDomain(
+    input: RiddlParserInput,
+    withVerboseFailures: Boolean = false
+  )(using PlatformContext): Either[Messages, Domain] =
+    val wrapped = RiddlParserInput(
+      s"domain SyntheticScope is {\n${input.data}\n}",
+      input.root
+    )
+    val tlp = new TopLevelParser(wrapped, withVerboseFailures)
+    tlp.parseDomainContents
+  end parseAsDomain
+
+  /** Parse content as if it were inside a Context body.
+    *
+    * Wraps the input in a synthetic `context SyntheticScope is { ... }`
+    * declaration, parses it, and returns the resulting Context.
+    *
+    * @param input The RiddlParserInput containing context-level content
+    * @param withVerboseFailures Enable verbose parse failure messages
+    * @return Either error messages or the parsed Context
+    */
+  def parseAsContext(
+    input: RiddlParserInput,
+    withVerboseFailures: Boolean = false
+  )(using PlatformContext): Either[Messages, Context] =
+    val wrapped = RiddlParserInput(
+      s"context SyntheticScope is {\n${input.data}\n}",
+      input.root
+    )
+    val tlp = new TopLevelParser(wrapped, withVerboseFailures)
+    tlp.parseContextContents
+  end parseAsContext
+
+  /** Parse content as if it were inside an Entity body.
+    *
+    * Wraps the input in a synthetic `entity SyntheticScope is { ... }`
+    * declaration, parses it, and returns the resulting Entity.
+    *
+    * @param input The RiddlParserInput containing entity-level content
+    * @param withVerboseFailures Enable verbose parse failure messages
+    * @return Either error messages or the parsed Entity
+    */
+  def parseAsEntity(
+    input: RiddlParserInput,
+    withVerboseFailures: Boolean = false
+  )(using PlatformContext): Either[Messages, Entity] =
+    val wrapped = RiddlParserInput(
+      s"entity SyntheticScope is {\n${input.data}\n}",
+      input.root
+    )
+    val tlp = new TopLevelParser(wrapped, withVerboseFailures)
+    tlp.parseEntityContents
+  end parseAsEntity
+
+  /** Parse content as if it were inside a Module body.
+    *
+    * Wraps the input in a synthetic `module SyntheticScope is { ... }`
+    * declaration, parses it, and returns the resulting Module.
+    */
+  def parseAsModule(
+    input: RiddlParserInput,
+    withVerboseFailures: Boolean = false
+  )(using PlatformContext): Either[Messages, Module] =
+    val wrapped = RiddlParserInput(
+      s"module SyntheticScope is {\n${input.data}\n}",
+      input.root
+    )
+    val tlp = new TopLevelParser(wrapped, withVerboseFailures)
+    tlp.parseModuleContents
+  end parseAsModule
+
+  /** Parse content as if it were inside an Adaptor body.
+    *
+    * Wraps the input in a synthetic adaptor declaration using
+    * the caller-provided direction and context reference, then
+    * parses it and returns the resulting Adaptor.
+    *
+    * @param input The RiddlParserInput containing adaptor body content
+    * @param direction The AdaptorDirection (InboundAdaptor or OutboundAdaptor)
+    * @param contextRef The ContextRef the adaptor adapts from/to
+    * @param withVerboseFailures Enable verbose parse failure messages
+    * @return Either error messages or the parsed Adaptor
+    */
+  def parseAsAdaptor(
+    input: RiddlParserInput,
+    direction: AdaptorDirection,
+    contextRef: ContextRef,
+    withVerboseFailures: Boolean = false
+  )(using PlatformContext): Either[Messages, Adaptor] =
+    val dirStr = direction match
+      case _: InboundAdaptor  => "from"
+      case _: OutboundAdaptor => "to"
+    val ctxPath = contextRef.pathId.value.mkString(".")
+    val wrapped = RiddlParserInput(
+      s"adaptor SyntheticScope $dirStr context $ctxPath is {\n${input.data}\n}",
+      input.root
+    )
+    val tlp = new TopLevelParser(wrapped, withVerboseFailures)
+    tlp.parseAdaptorContents
+  end parseAsAdaptor
+
+  /** Parse content as if it were inside a Projector body.
+    *
+    * Wraps the input in a synthetic `projector SyntheticScope is { ... }`
+    * declaration, parses it, and returns the resulting Projector.
+    */
+  def parseAsProjector(
+    input: RiddlParserInput,
+    withVerboseFailures: Boolean = false
+  )(using PlatformContext): Either[Messages, Projector] =
+    val wrapped = RiddlParserInput(
+      s"projector SyntheticScope is {\n${input.data}\n}",
+      input.root
+    )
+    val tlp = new TopLevelParser(wrapped, withVerboseFailures)
+    tlp.parseProjectorContents
+  end parseAsProjector
+
+  /** Parse content as if it were inside a Repository body.
+    *
+    * Wraps the input in a synthetic `repository SyntheticScope is { ... }`
+    * declaration, parses it, and returns the resulting Repository.
+    */
+  def parseAsRepository(
+    input: RiddlParserInput,
+    withVerboseFailures: Boolean = false
+  )(using PlatformContext): Either[Messages, Repository] =
+    val wrapped = RiddlParserInput(
+      s"repository SyntheticScope is {\n${input.data}\n}",
+      input.root
+    )
+    val tlp = new TopLevelParser(wrapped, withVerboseFailures)
+    tlp.parseRepositoryContents
+  end parseAsRepository
+
+  /** Parse content as if it were inside a Saga body.
+    *
+    * Parses the input for saga body content (saga steps,
+    * functions, inlets, outlets) and assembles a Saga using
+    * the caller-provided input/output aggregations.
+    *
+    * @param input The RiddlParserInput containing saga body content
+    * @param sagaInput Optional input aggregation from the parent Saga
+    * @param sagaOutput Optional output aggregation from the parent Saga
+    * @param withVerboseFailures Enable verbose parse failure messages
+    * @return Either error messages or the parsed Saga
+    */
+  def parseAsSaga(
+    input: RiddlParserInput,
+    sagaInput: Option[Aggregation] = None,
+    sagaOutput: Option[Aggregation] = None,
+    withVerboseFailures: Boolean = false
+  )(using PlatformContext): Either[Messages, Saga] =
+    val tlp = new TopLevelParser(input, withVerboseFailures)
+    tlp.parseSagaDefinitions.map { contents =>
+      val loc =
+        if contents.nonEmpty then contents.head.loc
+        else At.empty
+      Saga(loc, Identifier.empty, sagaInput, sagaOutput,
+        contents.toContents)
+    }
+  end parseAsSaga
+
+  /** Parse content as if it were inside an Epic body.
+    *
+    * Parses the input for epic body content (use cases, types,
+    * etc.) and assembles an Epic using the caller-provided
+    * UserStory.
+    *
+    * @param input The RiddlParserInput containing epic-level content
+    * @param userStory The UserStory from the parent Epic definition
+    * @param withVerboseFailures Enable verbose parse failure messages
+    * @return Either error messages or the parsed Epic
+    */
+  def parseAsEpic(
+    input: RiddlParserInput,
+    userStory: UserStory,
+    withVerboseFailures: Boolean = false
+  )(using PlatformContext): Either[Messages, Epic] =
+    val tlp = new TopLevelParser(input, withVerboseFailures)
+    tlp.parseEpicDefinitions.map { contents =>
+      val loc =
+        if contents.nonEmpty then contents.head.loc
+        else At.empty
+      Epic(loc, Identifier.empty, userStory, contents.toContents)
+    }
+  end parseAsEpic
+
+  /** Parse content as if it were inside a Streamlet body.
+    *
+    * Parses the input for processor content (handlers, types,
+    * functions, etc.) and assembles a Streamlet using the
+    * caller-provided shape, inlets, and outlets.
+    *
+    * @param input The RiddlParserInput containing streamlet body content
+    * @param shape The StreamletShape from the parent Streamlet definition
+    * @param inlets The Inlet definitions from the parent Streamlet
+    * @param outlets The Outlet definitions from the parent Streamlet
+    * @param withVerboseFailures Enable verbose parse failure messages
+    * @return Either error messages or the parsed Streamlet
+    */
+  def parseAsStreamlet(
+    input: RiddlParserInput,
+    shape: StreamletShape,
+    inlets: Seq[Inlet],
+    outlets: Seq[Outlet],
+    withVerboseFailures: Boolean = false
+  )(using PlatformContext): Either[Messages, Streamlet] =
+    val tlp = new TopLevelParser(input, withVerboseFailures)
+    tlp.parseStreamletDefinitions.map { contents =>
+      val allContents =
+        (inlets.asInstanceOf[Seq[StreamletContents]] ++
+          outlets.asInstanceOf[Seq[StreamletContents]] ++
+          contents)
+      val loc =
+        if allContents.nonEmpty then allContents.head.loc
+        else At.empty
+      Streamlet(loc, Identifier.empty, shape, allContents.toContents)
+    }
+  end parseAsStreamlet
+
 end TopLevelParser