chore: add support for comments in hidden endpoint file (#98)

* DEFI-2488: Add support for comments in hidden endpoints

* DEFI-2488: Update README

Author: lpahlavi

Cargo.toml

@@ -22,7 +22,7 @@ path = "src/bin/main.rs"
 required-features = ["exe"]
 
 [features]
-check-endpoints = ["dep:anyhow", "dep:candid_parser", "dep:parse-display"]
+check-endpoints = ["dep:anyhow", "dep:candid_parser", "dep:parse-display", "dep:serde_json"]
 default = ["check-endpoints", "exe", "wasm-opt"]
 exe = ["dep:anyhow", "dep:clap", "dep:serde"]
 wasm-opt = ["dep:wasm-opt", "dep:tempfile"]

README.md

@@ -97,22 +97,32 @@ Verify the endpoints a canister’s WASM exports against its Candid interface. T
 Usage: `ic-wasm <input.wasm> check-endpoints [--candid <file>] [--hidden <file>]`
 
 - `--candid <file>` (optional) specifies a Candid file containing the canister's expected interface. If omitted, the Candid interface is assumed to be embedded in the WASM file.
-- `--hidden <file>` (optional) specifies a file listing endpoints that are intentionally exported by the canister but not present in the Candid interface. Each endpoint should be on a separate line, using one of the following formats:
-    - `canister_update:<endpoint name>`
-    - `canister_query:<endpoint name>`
-    - `canister_composite_query:<endpoint name>`
-    - `<endpoint name>`
-
-**Example `hidden.txt`:**
-```text
-canister_update:__motoko_async_helper
-canister_query:__get_candid_interface_tmp_hack
-canister_query:__motoko_stable_var_info
-canister_global_timer
-canister_init
-canister_post_upgrade
-canister_pre_upgrade
-```
+- `--hidden <file>` (optional) specifies a file that lists endpoints which are intentionally exported by the canister but not included in the Candid interface. Each line describes a single endpoint using one of the following formats:
+  - `canister_update:<endpoint name>`
+  - `canister_query:<endpoint name>`
+  - `canister_composite_query:<endpoint name>`
+  - `<endpoint name>`
+
+  Lines beginning with `#` are treated as comments and ignored.
+
+  To include special characters (for example `#` or newlines), the entire line may be wrapped in double quotes (`"`). 
+  When quoted this way, the line is parsed using standard JSON string syntax (see [RFC 8259 section 7](https://www.rfc-editor.org/rfc/rfc8259#section-7)).
+  
+  **Example `hidden.txt`:**
+  ```text
+  # A canister update endpoint named `__motoko_async_helper`
+  canister_update:__motoko_async_helper
+  
+  # Canister query endpoints named `__get_candid_interface_tmp_hack` and `__motoko_stable_var_info`
+  canister_query:__get_candid_interface_tmp_hack
+  canister_query:__motoko_stable_var_info
+  
+  # Other canister endpoints: a timer, init method, etc.
+  canister_global_timer
+  canister_init
+  canister_post_upgrade
+  canister_pre_upgrade
+  ```
 
 ### Instrument (experimental)
 

src/check_endpoints/mod.rs

@@ -4,9 +4,8 @@ pub use crate::check_endpoints::candid::CandidParser;
 use crate::{info::ExportedMethodInfo, utils::get_exported_methods};
 use anyhow::anyhow;
 use parse_display::{Display, FromStr};
-use std::io::{BufRead, BufReader};
-use std::str::FromStr;
-use std::{collections::BTreeSet, path::Path};
+use std::io::BufReader;
+use std::{collections::BTreeSet, io::BufRead, path::Path, str::FromStr};
 use walrus::Module;
 
 #[derive(Clone, Eq, Debug, Ord, PartialEq, PartialOrd, Display, FromStr)]
@@ -112,22 +111,57 @@ pub fn check_endpoints(
 
 fn read_hidden_endpoints(maybe_path: Option<&Path>) -> anyhow::Result<BTreeSet<CanisterEndpoint>> {
     if let Some(path) = maybe_path {
-        let file = std::fs::File::open(path)
-            .map_err(|e| anyhow!("Failed to read hidden endpoints file: {e:?}"))?;
-        let reader = BufReader::new(file);
-        let lines = reader
-            .lines()
-            .collect::<Result<Vec<_>, _>>()
-            .map_err(|e| anyhow!("Failed to read hidden endpoints file: {e:?}"))?;
-        let endpoints = lines
-            .iter()
-            .map(|line| line.trim())
-            .filter(|line| !line.is_empty())
-            .map(CanisterEndpoint::from_str)
-            .collect::<Result<BTreeSet<_>, _>>()
-            .map_err(|e| anyhow!("Failed to parse hidden endpoints from file: {e:?}"))?;
+        let mut endpoints = BTreeSet::new();
+        for line in read_lines(path)? {
+            if let Some(endpoint) = parse_line(line)? {
+                endpoints.insert(endpoint);
+            }
+        }
         Ok(endpoints)
     } else {
         Ok(BTreeSet::new())
     }
 }
+
+fn read_lines(path: &Path) -> anyhow::Result<Vec<String>> {
+    let file = std::fs::File::open(path)
+        .map_err(|e| anyhow!("Could not open hidden endpoints file: {e:?}"))?;
+
+    let reader = BufReader::new(file);
+    let mut lines = Vec::new();
+
+    for line in reader.lines() {
+        let line = line?;
+        let trimmed = line.trim();
+        if !trimmed.is_empty() {
+            lines.push(trimmed.to_string());
+        }
+    }
+
+    Ok(lines)
+}
+
+fn parse_line(line: String) -> anyhow::Result<Option<CanisterEndpoint>> {
+    fn parse_uncommented_line(line: String) -> anyhow::Result<Option<CanisterEndpoint>> {
+        CanisterEndpoint::from_str(line.as_str())
+            .map(Some)
+            .map_err(Into::into)
+    }
+    // Comment: ignore line
+    if line.starts_with("#") {
+        return Ok(None);
+    }
+    // Quoted line: use JSON string syntax to allow for character escaping
+    if line.starts_with('"') {
+        if !line.ends_with('"') || line.len() < 2 {
+            return Err(anyhow!(
+                "Could not parse hidden endpoint, missing terminating quote: {line}"
+            ));
+        }
+        return serde_json::from_str::<String>(&line)
+            .map_err(|e| anyhow!("Could not parse hidden endpoint: {e:?}"))
+            .and_then(parse_uncommented_line);
+    }
+    // Regular line
+    parse_uncommented_line(line)
+}

tests/tests.rs

@@ -422,7 +422,9 @@ fn check_endpoints() {
         )
         .failure();
     const HIDDEN_1: &str = r#"
+    # Canister update method (this line is a comment)
     canister_update:set
+    # Canister query method (this line is also a comment)
     canister_query:get
     "#;
     wasm_input("wat.wasm.gz", false)
@@ -472,7 +474,8 @@ fn check_endpoints() {
     canister_global_timer
     canister_init
     canister_post_upgrade
-    canister_pre_upgrade
+    # The line below is quoted, it is parsed as a JSON string (this line is a comment)
+    "canister_pre_upgrade"
     "#;
     wasm_input("motoko.wasm", false)
         .arg("check-endpoints")