Parser and Concrete Syntax Tree

-- | Parse a PureScript module from text
parseModule :: Text -> Either ParseError (CST.Module SourceAnn)

-- | Parse module with custom filename
parseModuleFromFile :: FilePath -> Text -> Either ParseError (CST.Module SourceAnn)

-- | Parse multiple modules
parseModules :: [(FilePath, Text)] -> ([CST.Module SourceAnn], [ParseError])

-- | Parse error information
data ParseError = ParseError
  { parseErrorMessage :: String
  , parseErrorPosition :: SourcePos
  , parseErrorFilename :: Maybe FilePath
  }

-- | Parse expression from text
parseExpr :: Text -> Either ParseError (CST.Expr SourceAnn)

-- | Parse type from text  
parseType :: Text -> Either ParseError (CST.Type SourceAnn)

-- | Parse declaration from text
parseDecl :: Text -> Either ParseError (CST.Declaration SourceAnn)

-- | Parse import declaration
parseImportDecl :: Text -> Either ParseError (CST.ImportDecl SourceAnn)

-- | CST Module
data Module a = Module
  { modAnn :: a
  , modKeyword :: Token
  , modName :: Name ModuleName
  , modExports :: Maybe (DelimitedNonEmpty (Export a))
  , modWhere :: Token
  , modImports :: [ImportDecl a]
  , modDecls :: [Declaration a]
  }

-- | CST Declaration
data Declaration a
  = DeclData (DataHead a) (Maybe (Token, Separated (DataCtor a)))
  | DeclType (DataHead a) Token (Type a)
  | DeclNewtype (DataHead a) Token (Name (ProperName 'ConstructorName)) (Type a)
  | DeclClass (ClassHead a) (Maybe (Token, NonEmpty (Labeled (Name Ident) (Type a))))
  | DeclInstance (InstanceHead a) (Maybe (Token, NonEmpty (Instance Body a)))
  | DeclDerive Token (Maybe Token) (InstanceHead a)
  | DeclKindSignature Token (Labeled (Name (ProperName 'TypeName)) (Type a))
  | DeclSignature (Labeled (Name Ident) (Type a))
  | DeclValue (ValueBindingFields a)
  | DeclFixity (FixityFields a)
  | DeclForeign Token Token (Foreign a)
  | DeclRole Token Token (Name (ProperName 'TypeName)) (NonEmpty Role)

-- | CST Expression  
data Expr a
  = ExprHole a (Name Ident)
  | ExprSection a
  | ExprIdent a (QualifiedName Ident)
  , ExprConstructor a (QualifiedName (ProperName 'ConstructorName))
  | ExprBoolean a Bool Token
  | ExprChar a Char Token
  | ExprString a PSString Token  
  | ExprNumber a (Either Integer Double) Token
  | ExprArray a (Delimited (Expr a))
  | ExprRecord a (Delimited (RecordLabeled (Expr a)))
  | ExprParens a (Wrapped (Expr a))
  | ExprTyped a (Expr a) Token (Type a)
  | ExprInfix a (Expr a) (NonEmpty (Wrapped (QualifiedName (OpName 'ValueOpName)), Expr a))
  | ExprOp a (Expr a) (QualifiedName (OpName 'ValueOpName)) (Expr a)
  | ExprOpName a (QualifiedName (OpName 'ValueOpName))
  | ExprNegate a Token (Expr a)
  | ExprRecordAccessor a (RecordAccessor a)
  | ExprRecordUpdate a (Expr a) (DelimitedNonEmpty (RecordUpdate a))
  | ExprApp a (Expr a) (NonEmpty (Expr a))
  | ExprLambda a (Lambda a)
  | ExprIf a (IfThenElse a)
  | ExprCase a (CaseOf a)
  | ExprLet a (LetIn a)
  | ExprDo a (DoBlock a)
  | ExprAdo a (AdoBlock a)

-- | Lexical tokens
data Token
  = TokLeftParen SourceRange
  | TokRightParen SourceRange
  | TokLeftBrace SourceRange
  | TokRightBrace SourceRange
  | TokLeftSquare SourceRange
  | TokRightSquare SourceRange
  | TokLeftArrow SourceRange
  | TokRightArrow SourceRange
  | TokRightFatArrow SourceRange
  | TokDoubleColon SourceRange
  | TokForall SourceRange
  | TokEquals SourceRange
  | TokPipe SourceRange
  | TokDot SourceRange
  | TokComma SourceRange
  | TokUnderscore SourceRange
  | TokBackslash SourceRange
  -- ... more tokens

-- | Token range information
data SourceRange = SourceRange SourcePos SourcePos

-- | Extract token range
tokRange :: Token -> SourceRange

-- | Extract token text
tokText :: Token -> Text

-- | Layout context
data LayoutContext
  = LayoutLet
  | LayoutWhere  
  | LayoutOf
  | LayoutDo
  | LayoutAdo

-- | Process layout for token stream
processLayout :: [Token] -> [Token]

-- | Insert layout tokens
insertLayout :: [LayoutContext] -> [Token] -> [Token]

-- | Remove layout tokens (for pretty printing)
removeLayout :: [Token] -> [Token]

-- | Layout delimiter tokens
data LayoutDelim
  = LayoutStart
  | LayoutSep
  | LayoutEnd

-- | Recoverable parse error
data RecoverableParseError = RecoverableParseError
  { rpeError :: ParseError
  , rpeRecovery :: Maybe (CST.Module SourceAnn)
  }

-- | Parse with error recovery
parseModuleWithRecovery :: Text -> Either RecoverableParseError (CST.Module SourceAnn)

-- | Parse result with partial success
data ParseResult a
  = ParseSucceeded a
  | ParseFailed ParseError
  | ParsePartial a [ParseError]

-- | Parse with partial results
parseModulePartial :: Text -> ParseResult (CST.Module SourceAnn)

-- | Convert CST module to AST
convertModule :: CST.Module SourceAnn -> Either MultipleErrors (Module SourceAnn)

-- | Convert CST declaration to AST
convertDeclaration :: CST.Declaration SourceAnn -> Either MultipleErrors (Declaration SourceAnn)

-- | Convert CST expression to AST
convertExpr :: CST.Expr SourceAnn -> Either MultipleErrors (Expr SourceAnn)

-- | Convert CST type to AST
convertType :: CST.Type SourceAnn -> Either MultipleErrors (SourceType)

-- | Convert CST binder to AST
convertBinder :: CST.Binder SourceAnn -> Either MultipleErrors (Binder SourceAnn)

-- | Pretty print CST module
printModule :: CST.Module SourceAnn -> Text

-- | Pretty print CST declaration
printDeclaration :: CST.Declaration SourceAnn -> Text

-- | Pretty print CST expression
printExpr :: CST.Expr SourceAnn -> Text

-- | Pretty print CST type
printType :: CST.Type SourceAnn -> Text

-- | Pretty print options
data PrintOptions = PrintOptions
  { printUnicode :: Bool          -- Use unicode syntax
  , printWidth :: Int             -- Maximum line width
  , printIndent :: Int            -- Indentation size
  , printTabWidth :: Int          -- Tab width
  }

-- | Default print options
defaultPrintOptions :: PrintOptions

-- | Pretty print with options
printModuleWithOptions :: PrintOptions -> CST.Module SourceAnn -> Text

-- | Comment types
data Comment
  = LineComment Text
  | BlockComment Text

-- | Comment attachment
data CommentedToken = CommentedToken
  { ctToken :: Token
  , ctLeading :: [Comment]
  , ctTrailing :: [Comment]
  }

-- | Parse with comments
parseModuleWithComments :: Text -> Either ParseError (CST.Module SourceAnn, [Comment])

-- | Attach comments to CST
attachComments :: [Comment] -> CST.Module SourceAnn -> CST.Module SourceAnn

-- | Extract comments from CST
extractComments :: CST.Module SourceAnn -> [Comment]

-- | Get CST node position
class HasPosition a where
  getPosition :: a -> SourceAnn

-- | Update CST node position  
class SetPosition a where
  setPosition :: SourceAnn -> a -> a

-- | Extract source span from CST
getSourceSpan :: CST.Module SourceAnn -> SourceSpan

-- | Find CST node at position
findNodeAtPosition :: SourcePos -> CST.Module SourceAnn -> Maybe (CST.Declaration SourceAnn)

-- | Get enclosing nodes at position
getEnclosingNodes :: SourcePos -> CST.Module SourceAnn -> [CST.Declaration SourceAnn]

-- | Names in CST
data Name a = Name
  { nameAnn :: SourceAnn
  , nameTok :: Token
  , nameValue :: a
  }

-- | Qualified names
data QualifiedName a = QualifiedName
  { qualTok :: Token
  , qualModule :: ModuleName
  , qualName :: Name a
  }

-- | Separated lists (comma-separated)
data Separated a = Separated a [(Token, a)]

-- | Non-empty separated lists
type NonEmpty a = Separated a

-- | Delimited constructs (parentheses, brackets, braces)
data Delimited a = Delimited Token (Maybe (Separated a)) Token

-- | Wrapped constructs  
data Wrapped a = Wrapped Token a Token

-- | Labeled constructs (name :: type)
data Labeled name a = Labeled name Token a

-- | Operator precedence levels
data Precedence = Precedence Int

-- | Operator associativity
data Associativity = AssocLeft | AssocRight | AssocNone

-- | Operator fixity information
data OpTable = OpTable (M.Map (Qualified (OpName 'ValueOpName)) (Precedence, Associativity))

-- | Default operator table
defaultOpTable :: OpTable

-- | Add operator to table
addOperator :: Qualified (OpName 'ValueOpName) -> Precedence -> Associativity -> OpTable -> OpTable