Merge #354: feat: unstable with traits

b8d2b34 Add unstable features docs (Sdoba16)
822af47 Add unstable features check to compiler (Sdoba16)
105f2ca Add RequireFeature trait for current AST nodes (Sdoba16)
b8b83f7 Add unstable features basic functionality (Sdoba16)

Pull request description:

  Closes #317

  Replaces #329

  Added `UnstableFeature` enum to track available unstable features
  Added `UnstableFeatures` to check whether a feature is enabled

  Added `RequireFeature` trait, implemented for every AST node. Each node reports which unstable features it requires. Struct impls use full field destructuring and enum impls use exhaustive matches, so new nodes or fields cause a compile error until the impl is updated.

  The check runs at parse time: once a program parses without errors, any use of a disabled feature is reported with an error naming the feature and the `-Z` flag that enables it.

  Added a `-Z <feature>` flag to the CLI. Multiple features can be passed with repeated flags. Available features are listed in the help output.

  `simc program.simf -Z imports`

  Added `doc/unstable-features.md` with user and developer guides.

ACKs for top commit:
  KyrylR:
    ACK b8d2b34; successfully ran local tests

Tree-SHA512: af9b3f392692605bffd4dec1bd40acd47d27d98c483360fe17be531095c2cdf98476f1c05706115a0c732db5f0c7b023681ac0cda4bed87302dac6a16f87b3bf

Author: KyrylR

doc/unstable-features.md

@@ -0,0 +1,17 @@
+# Unstable features
+
+Unstable features are experimental compiler capabilities. They may change
+or be removed before stabilization.
+
+## Viewing available unstable features
+
+Run `simc --help`; the features are listed under the `-Z` flag.
+
+## Enabling an unstable feature
+
+Pass `-Z <feature-name>` to `simc`.
+
+## Adding or stabilizing a feature
+
+See the rustdoc on `UnstableFeature` in `src/unstable.rs`; the procedures
+live next to the code they mutate, so they cannot drift.

src/compile/mod.rs

@@ -63,7 +63,6 @@ struct Scope<'brand> {
     ///
     /// Inner scopes occur higher in the tree than outer scopes.
     /// Later assignments occur higher in the tree than earlier assignments.
-    /// ```
     variables: Vec<Vec<Pattern>>,
     ctx: simplicity::types::Context<'brand>,
     /// Tracker of function calls.

src/driver/mod.rs

@@ -1,3 +1,4 @@
+#![allow(rustdoc::private_intra_doc_links)]
 //! The `driver` module is responsible for module resolution and dependency management.
 //!
 //! Our compiler operates in a strict pipeline: `Lexer -> Parser -> Driver -> AST`.
@@ -36,6 +37,7 @@ use crate::error::{Error, ErrorCollector, RichError, Span};
 use crate::parse::{self, ParseFromStrWithErrors};
 use crate::resolution::{DependencyMap, ResolvedUse};
 use crate::source::{CanonPath, CanonSourceFile};
+use crate::unstable::UnstableFeatures;
 
 /// The reserved identifier for the program's entry point.
 pub(crate) const MAIN_STR: &str = "main";
@@ -178,6 +180,7 @@ impl DependencyGraph {
         dependency_map: Arc<DependencyMap>,
         root_program: &parse::Program,
         handler: &mut ErrorCollector,
+        unstable_features: &UnstableFeatures,
     ) -> Result<Option<Self>, String> {
         let mut graph = Self {
             modules: vec![SourceModule {
@@ -226,6 +229,7 @@ impl DependencyGraph {
                 invalid_imports: &mut invalid_imports,
                 handler,
                 queue: &mut queue,
+                unstable_features,
             };
             graph.load_and_parse_dependencies(&current, valid_imports, &mut ctx);
         }
@@ -246,6 +250,7 @@ impl DependencyGraph {
         importer_source: &CanonSourceFile,
         span: Span,
         handler: &mut ErrorCollector,
+        unstable_features: &UnstableFeatures,
     ) -> Option<SourceModule> {
         let Ok(content) = std::fs::read_to_string(path.as_path()) else {
             let err = RichError::new(
@@ -263,7 +268,11 @@ impl DependencyGraph {
         let mut error_handler = ErrorCollector::new();
         let source = CanonSourceFile::new(path.clone(), Arc::from(content));
 
-        let ast = parse::Program::parse_from_str_with_errors(source.clone(), &mut error_handler);
+        let ast = parse::Program::parse_from_str_with_errors(
+            source.clone(),
+            unstable_features,
+            &mut error_handler,
+        );
 
         if error_handler.has_errors() {
             handler.extend_with_handler(source, &error_handler);
@@ -321,9 +330,13 @@ impl DependencyGraph {
                 continue;
             }
 
-            let Some(module) =
-                Self::parse_and_get_source_module(&path, &current.source, import_span, ctx.handler)
-            else {
+            let Some(module) = Self::parse_and_get_source_module(
+                &path,
+                &current.source,
+                import_span,
+                ctx.handler,
+                ctx.unstable_features,
+            ) else {
                 // Safe to ignore output: previous `.contains` check prevents collisions.
                 let _ = ctx.invalid_imports.insert(path);
                 continue;
@@ -346,7 +359,7 @@ impl DependencyGraph {
 }
 
 /// Groups all shared state for import resolution to avoid threading a lot of parameters
-/// through every recursive call. Lives only for the duration of [`resolve_imports`].
+/// through every recursive call. Lives only for the duration of [`DependencyGraph::resolve_imports`].
 struct ImportContext<'a> {
     current: CurrentModule,
     dependency_map: &'a DependencyMap,
@@ -421,6 +434,7 @@ struct LoadContext<'a> {
     invalid_imports: &'a mut HashSet<CanonPath>,
     handler: &'a mut ErrorCollector,
     queue: &'a mut VecDeque<usize>,
+    unstable_features: &'a UnstableFeatures,
 }
 
 /// The currently processed module and its source, used for error reporting
@@ -493,15 +507,24 @@ pub(crate) mod tests {
         let root_p = root_file_path.expect("main.simf must be defined in file list");
         let main_canon_source = CanonSourceFile::new(root_p, Arc::from(root_content));
 
-        let main_program_option =
-            parse::Program::parse_from_str_with_errors(main_canon_source.clone(), &mut handler);
+        let main_program_option = parse::Program::parse_from_str_with_errors(
+            main_canon_source.clone(),
+            &UnstableFeatures::all(),
+            &mut handler,
+        );
 
         let Some(main_program) = main_program_option else {
             return (None, HashMap::new(), ws, handler);
         };
 
-        let graph_option =
-            DependencyGraph::new(main_canon_source, map, &main_program, &mut handler).unwrap();
+        let graph_option = DependencyGraph::new(
+            main_canon_source,
+            map,
+            &main_program,
+            &mut handler,
+            &UnstableFeatures::all(),
+        )
+        .unwrap();
 
         let mut file_ids = HashMap::new();
 

src/error.rs

@@ -18,6 +18,7 @@ use crate::parse::MatchPattern;
 use crate::source::SourceFile;
 use crate::str::{AliasName, FunctionName, Identifier, JetName, ModuleName, WitnessName};
 use crate::types::{ResolvedType, UIntType};
+use crate::unstable::UnstableFeature;
 
 /// Area that an object spans inside a file.
 #[derive(Copy, Clone, Debug, Eq, PartialEq, Hash)]
@@ -478,6 +479,9 @@ impl fmt::Display for ErrorCollector {
 /// Records _what_ happened but not where.
 #[derive(Debug, Clone)]
 pub enum Error {
+    UnstableFeature {
+        feature: UnstableFeature,
+    },
     DependencyPathNotFound {
         path: PathBuf,
     },
@@ -643,15 +647,16 @@ pub enum Error {
         declared: ResolvedType,
         assigned: ResolvedType,
     },
-    // TODO: Remove these once `use` and `mod` are supported by the AST
-    UseKeywordIsNotSupported,
-    ModuleKeywordIsNotSupported,
 }
 
 #[rustfmt::skip]
 impl fmt::Display for Error {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {
+            Error::UnstableFeature { feature } => write!(
+                f,
+                "The '{feature}' feature is not enabled.\nEnable it with: -Z {feature}"
+            ),
             Error::DependencyPathNotFound { path } => write!(
                 f,
                 "Path not found: {}", path.display()
@@ -880,14 +885,6 @@ impl fmt::Display for Error {
                 f,
                 "Parameter `{name}` was declared with type `{declared}` but its assigned argument is of type `{assigned}`"
             ),
-            Error::UseKeywordIsNotSupported => write!(
-                f,
-                "The `use` keyword is not supported yet"
-            ),
-            Error::ModuleKeywordIsNotSupported => write!(
-                f,
-                "The `mod` keyword is not supported yet"
-            ),
         }
     }
 }