1 /*
2 * Copyright (C) 2025 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 //! `exported-flag-check` is a tool to ensures that exported flags are used as intended
18 use anyhow::{ensure, Result};
19 use clap::Parser;
20 use std::{collections::HashSet, fs::File, path::PathBuf};
21
22 mod utils;
23
24 use utils::{
25 check_all_exported_flags, extract_flagged_api_flags, get_exported_flags_from_binary_proto,
26 read_finalized_flags,
27 };
28
29 const ABOUT: &str = "CCheck Exported Flags
30
31 This tool ensures that exported flags are used as intended. Exported flags, marked with
32 `is_exported: true` in their declaration, are designed to control access to specific API
33 features. This tool identifies and reports any exported flags that are not currently
34 associated with an API feature, preventing unnecessary flag proliferation and maintaining
35 a clear API design.
36
37 This tool works as follows:
38
39 - Read API signature files from source tree (*current.txt files) [--api-signature-file]
40 - Read the current aconfig flag values from source tree [--parsed-flags-file]
41 - Read the previous finalized-flags.txt files from prebuilts/sdk [--finalized-flags-file]
42 - Extract the flags slated for API by scanning through the API signature files
43 - Merge the found flags with the recorded flags from previous API finalizations
44 - Error if exported flags are not in the set
45 ";
46
47 #[derive(Parser, Debug)]
48 #[clap(about=ABOUT)]
49 struct Cli {
50 #[arg(long)]
51 parsed_flags_file: PathBuf,
52
53 #[arg(long)]
54 api_signature_file: Vec<PathBuf>,
55
56 #[arg(long)]
57 finalized_flags_file: PathBuf,
58 }
59
main() -> Result<()>60 fn main() -> Result<()> {
61 let args = Cli::parse();
62
63 let mut flags_used_with_flaggedapi_annotation = HashSet::new();
64 for path in &args.api_signature_file {
65 let file = File::open(path)?;
66 let flags = extract_flagged_api_flags(file)?;
67 flags_used_with_flaggedapi_annotation.extend(flags);
68 }
69
70 let file = File::open(args.parsed_flags_file)?;
71 let all_flags = get_exported_flags_from_binary_proto(file)?;
72
73 let file = File::open(args.finalized_flags_file)?;
74 let already_finalized_flags = read_finalized_flags(file)?;
75
76 let exported_flags = check_all_exported_flags(
77 &flags_used_with_flaggedapi_annotation,
78 &all_flags,
79 &already_finalized_flags,
80 )?;
81
82 println!("{}", exported_flags.join("\n"));
83
84 ensure!(
85 exported_flags.is_empty(),
86 "Flags {} are exported but not used to guard any API. \
87 Exported flag should be used to guard API",
88 exported_flags.join(",")
89 );
90 Ok(())
91 }
92
93 #[cfg(test)]
94 mod tests {
95 use super::*;
96
97 #[test]
test()98 fn test() {
99 let input = include_bytes!("../tests/api-signature-file.txt");
100 let flags_used_with_flaggedapi_annotation = extract_flagged_api_flags(&input[..]).unwrap();
101
102 let input = include_bytes!("../tests/flags.protobuf");
103 let all_flags_to_be_finalized = get_exported_flags_from_binary_proto(&input[..]).unwrap();
104
105 let input = include_bytes!("../tests/finalized-flags.txt");
106 let already_finalized_flags = read_finalized_flags(&input[..]).unwrap();
107
108 let exported_flags = check_all_exported_flags(
109 &flags_used_with_flaggedapi_annotation,
110 &all_flags_to_be_finalized,
111 &already_finalized_flags,
112 )
113 .unwrap();
114
115 assert_eq!(1, exported_flags.len());
116 }
117 }
118