feat: annotations (#9)

```rs
@some_annotation
fn my_thing() {
    // ...
}

@some_annotation(value)
trait MyTrait {
    // ...
}
```

Author: andogq

src/ir/ast.rs

@@ -10,6 +10,7 @@ create_id!(FunctionId);
 create_id!(StatementId);
 create_id!(AstTypeId);
 create_id!(TraitId);
+create_id!(AnnotationId);
 
 #[derive(Clone, Debug)]
 pub struct Ast {
@@ -18,6 +19,7 @@ pub struct Ast {
     pub blocks: IndexedVec<BlockId, Block>,
     pub statements: IndexedVec<StatementId, Statement>,
     pub expressions: IndexedVec<ExpressionId, Expression>,
+    pub annotations: IndexedVec<AnnotationId, Annotation>,
 
     pub types: IndexedVec<AstTypeId, AstType>,
 
@@ -35,6 +37,7 @@ impl Ast {
             blocks: IndexedVec::new(),
             statements: IndexedVec::new(),
             expressions: IndexedVec::new(),
+            annotations: IndexedVec::new(),
             types: IndexedVec::new(),
             item_functions: Vec::new(),
             traits: IndexedVec::new(),
@@ -75,6 +78,14 @@ impl Index<StatementId> for Ast {
     }
 }
 
+impl Index<AnnotationId> for Ast {
+    type Output = Annotation;
+
+    fn index(&self, index: AnnotationId) -> &Self::Output {
+        &self.annotations[index]
+    }
+}
+
 impl Index<AstTypeId> for Ast {
     type Output = AstType;
 
@@ -102,6 +113,16 @@ pub enum AstType {
     Tuple(Vec<AstTypeId>),
 }
 
+/// An annotation attached to an item.
+#[derive(Clone, Debug)]
+#[expect(dead_code, reason = "annotations not used yet")]
+pub struct Annotation {
+    /// Key of the annotation.
+    pub key: StringId,
+    /// Value of the annotation, which may or may not be present.
+    pub value: Option<StringId>,
+}
+
 mod function {
     use super::*;
 
@@ -113,7 +134,9 @@ mod function {
     }
 
     #[derive(Clone, Debug)]
+    #[expect(dead_code, reason = "annotations not used yet")]
     pub struct FunctionDeclaration {
+        pub annotations: Vec<AnnotationId>,
         pub signature: FunctionSignature,
         pub body: BlockId,
     }
@@ -289,6 +312,9 @@ mod expression {
 
 #[derive(Clone, Debug)]
 pub struct Trait {
+    /// Annotations attached to this trait.
+    #[expect(dead_code, reason = "annotations not used yet")]
+    pub annotations: Vec<AnnotationId>,
     /// Original name of the trait.
     pub name: StringId,
     /// Methods defined within the trait.
@@ -297,6 +323,9 @@ pub struct Trait {
 
 #[derive(Clone, Debug)]
 pub struct TraitImplementation {
+    /// Annotations attached to this trait implementation.
+    #[expect(dead_code, reason = "annotations not used yet")]
+    pub annotations: Vec<AnnotationId>,
     pub trait_name: StringId,
     pub target_ty: AstTypeId,
     pub methods: BTreeMap<StringId, FunctionId>,

src/ir/cst.rs

@@ -19,30 +19,56 @@ impl Program {
     pub const fn new() -> Self {
         Self { items: Vec::new() }
     }
-
-    pub fn add_function_declaration(&mut self, function_declaration: FunctionDeclaration) {
-        self.items
-            .push(Item::FunctionDeclaration(function_declaration));
-    }
-
-    pub fn add_trait_declaration(&mut self, trait_declaration: TraitDeclaration) {
-        self.items.push(Item::TraitDeclaration(trait_declaration));
-    }
-
-    pub fn add_trait_implementation(&mut self, trait_implementation: TraitImplementation) {
-        self.items
-            .push(Item::TraitImplementation(trait_implementation));
-    }
 }
 
 /// A node which may appear at the top-level of a program.
 #[derive(Clone, Debug)]
-pub enum Item {
+pub struct Item {
+    /// Annotations attached to this item.
+    pub annotations: Vec<Annotation>,
+    /// The actual item.
+    pub kind: ItemKind,
+}
+
+#[derive(Clone, Debug)]
+pub enum ItemKind {
     TraitDeclaration(TraitDeclaration),
     TraitImplementation(TraitImplementation),
     FunctionDeclaration(FunctionDeclaration),
 }
 
+/// An annotation the source, which may or may not have a value.
+///
+/// ```
+/// @some_annotation
+///
+/// @some_annotation(with_value)
+/// ```
+#[derive(Clone, Debug)]
+pub struct Annotation {
+    #[expect(dead_code, reason = "token field")]
+    pub tok_at: tok::At,
+    /// Key of the annotation.
+    pub key: tok::Ident,
+    /// Value of the annotation.
+    pub value: AnnotationValue,
+}
+
+/// Value for an annotation.
+#[derive(Clone, Debug)]
+pub enum AnnotationValue {
+    /// No value.
+    None,
+    /// Value within parenthesis.
+    Value {
+        #[expect(dead_code, reason = "token field")]
+        tok_l_parenthesis: tok::LParenthesis,
+        value: tok::Ident,
+        #[expect(dead_code, reason = "token field")]
+        tok_r_parenthesis: tok::RParenthesis,
+    },
+}
+
 /// Trait declaration.
 ///
 /// ```

src/lex/mod.rs

@@ -189,6 +189,10 @@ impl<'src> Lexer<'src> {
                     _ => Tok::Bang,
                 }
             }
+            '@' => {
+                self.expect_char('@');
+                Tok::At
+            }
             '=' => {
                 self.expect_char('=');
 
@@ -341,6 +345,8 @@ mod test {
     #[case("::", &[Tok::ColonColon, Tok::Eof])]
     #[case(";", &[Tok::SemiColon, Tok::Eof])]
     #[case(",", &[Tok::Comma, Tok::Eof])]
+    #[case("!", &[Tok::Bang, Tok::Eof])]
+    #[case("@", &[Tok::At, Tok::Eof])]
     #[case("==", &[Tok::EqEq, Tok::Eof])]
     #[case("!=", &[Tok::BangEq, Tok::Eof])]
     #[case(">=", &[Tok::GtEq, Tok::Eof])]

src/lex/tok.rs

@@ -113,6 +113,7 @@ toks! {
     Dot => ".",
     Comma => ",",
     Bang => "!",
+    At => "@",
 
     EqEq => "==",
     BangEq => "!=",

src/passes/ast_gen.rs

@@ -17,15 +17,21 @@ impl<'ctx, 'cst> Pass<'ctx, 'cst> for AstGen<'ctx> {
         let mut ast_gen = Self::new(ctx);
 
         for item in &cst.items {
-            match item {
-                cst::Item::FunctionDeclaration(function_declaration) => {
-                    ast_gen.lower_item_function(function_declaration);
+            let annotations = item
+                .annotations
+                .iter()
+                .map(|annotation| ast_gen.lower_annotation(annotation))
+                .collect();
+
+            match &item.kind {
+                cst::ItemKind::FunctionDeclaration(function_declaration) => {
+                    ast_gen.lower_item_function(function_declaration, annotations);
                 }
-                cst::Item::TraitDeclaration(trait_declaration) => {
-                    ast_gen.lower_trait_declaration(trait_declaration);
+                cst::ItemKind::TraitDeclaration(trait_declaration) => {
+                    ast_gen.lower_trait_declaration(trait_declaration, annotations);
                 }
-                cst::Item::TraitImplementation(trait_implementation) => {
-                    ast_gen.lower_trait_implementation(trait_implementation);
+                cst::ItemKind::TraitImplementation(trait_implementation) => {
+                    ast_gen.lower_trait_implementation(trait_implementation, annotations);
                 }
             }
         }
@@ -42,16 +48,38 @@ impl<'ctx> AstGen<'ctx> {
         }
     }
 
-    fn lower_function(&mut self, function: &cst::FunctionDeclaration) -> FunctionId {
+    fn lower_annotation(&mut self, annotation: &cst::Annotation) -> AnnotationId {
+        let annotation = Annotation {
+            key: self.ctx.strings.intern(&annotation.key.0),
+            value: match &annotation.value {
+                cst::AnnotationValue::None => None,
+                cst::AnnotationValue::Value { value, .. } => {
+                    Some(self.ctx.strings.intern(&value.0))
+                }
+            },
+        };
+        self.ast.annotations.insert(annotation)
+    }
+
+    fn lower_function(
+        &mut self,
+        function: &cst::FunctionDeclaration,
+        annotations: Vec<AnnotationId>,
+    ) -> FunctionId {
         let function_declaration = FunctionDeclaration {
+            annotations,
             signature: self.lower_function_signature(&function.signature),
             body: self.lower_block(&function.body),
         };
         self.ast.function_declarations.insert(function_declaration)
     }
 
-    fn lower_item_function(&mut self, function: &cst::FunctionDeclaration) -> FunctionId {
-        let id = self.lower_function(function);
+    fn lower_item_function(
+        &mut self,
+        function: &cst::FunctionDeclaration,
+        annotations: Vec<AnnotationId>,
+    ) -> FunctionId {
+        let id = self.lower_function(function, annotations);
         self.ast.item_functions.push(id);
         id
     }
@@ -286,7 +314,11 @@ impl<'ctx> AstGen<'ctx> {
     }
 
     /// Lower a [`cst::TraitDeclaration`] into a [`Trait`], producing a unique [`TraitId`].
-    fn lower_trait_declaration(&mut self, trait_declaration: &cst::TraitDeclaration) -> TraitId {
+    fn lower_trait_declaration(
+        &mut self,
+        trait_declaration: &cst::TraitDeclaration,
+        annotations: Vec<AnnotationId>,
+    ) -> TraitId {
         let methods = trait_declaration
             .methods
             .iter()
@@ -298,23 +330,33 @@ impl<'ctx> AstGen<'ctx> {
             })
             .collect();
         self.ast.traits.insert(Trait {
+            annotations,
             name: self.ctx.strings.intern(&trait_declaration.name.0),
             methods,
         })
     }
 
-    fn lower_trait_implementation(&mut self, trait_implementation: &cst::TraitImplementation) {
+    fn lower_trait_implementation(
+        &mut self,
+        trait_implementation: &cst::TraitImplementation,
+        annotations: Vec<AnnotationId>,
+    ) {
         let methods = trait_implementation
             .methods
             .iter()
             .map(|method| {
-                let method = self.lower_function(method);
+                let method = self.lower_function(
+                    method,
+                    // Currently, annotations cannot be attached to non-item functions.
+                    Vec::new(),
+                );
 
                 (self.ast[method].signature.name, method)
             })
             .collect();
         let target_ty = self.lower_type(&trait_implementation.ty);
         self.ast.trait_implementations.push(TraitImplementation {
+            annotations,
             trait_name: self.ctx.strings.intern(&trait_implementation.name.0),
             target_ty,
             methods,
@@ -389,7 +431,7 @@ mod test {
     )]
     fn trait_declaration(#[case] name: &str, mut ctx: Ctx, #[case] source: &'static str) {
         let mut pass = AstGen::new(&mut ctx);
-        let trait_id = pass.lower_trait_declaration(&parse(source));
+        let trait_id = pass.lower_trait_declaration(&parse(source), Vec::new());
         assert_debug_snapshot!(name, pass.ast[trait_id], source);
     }
 
@@ -405,7 +447,16 @@ mod test {
     )]
     fn trait_implementation(#[case] name: &str, mut ctx: Ctx, #[case] source: &'static str) {
         let mut pass = AstGen::new(&mut ctx);
-        pass.lower_trait_implementation(&parse(source));
+        pass.lower_trait_implementation(&parse(source), Vec::new());
         assert_debug_snapshot!(name, pass.ast.trait_implementations[0], source);
     }
+
+    #[rstest]
+    #[case("annotation_key", "@some_annotation")]
+    #[case("annotation_key_value", "@some_annotation(value)")]
+    fn lower_annotation(#[case] name: &str, mut ctx: Ctx, #[case] source: &str) {
+        let mut pass = AstGen::new(&mut ctx);
+        let annotation = pass.lower_annotation(&parse(source));
+        assert_debug_snapshot!(name, pass.ast.annotations[annotation], source);
+    }
 }