use super::CommentStyle;
use super::generate::generate_with;
use super::parse::{
detect, detect_style_from_content, detect_style_from_header, is_comment_line,
is_comment_line_in, is_plain_copyright_notice, leading_comment_marker, strip_comment_prefix,
};
use super::prefix::CopyrightNotice;
use super::style::{ResolvedStyle, block_delimiters, configured_prefixes};
use crate::config::CommentStyleRule;
use crate::error::Error;
#[allow(clippy::missing_errors_doc)]
pub fn annotate_file<'a>(
content: &str,
copyright: impl Into<CopyrightNotice<'a>>,
license_expression: &str,
style_override: Option<ResolvedStyle<'_>>,
force: bool,
) -> Result<String, Error> {
annotate_file_with(
content,
copyright,
license_expression,
style_override,
force,
&[],
false,
)
}
#[allow(clippy::missing_errors_doc)]
pub fn annotate_file_with<'a>(
content: &str,
copyright: impl Into<CopyrightNotice<'a>>,
license_expression: &str,
style_override: Option<ResolvedStyle<'_>>,
force: bool,
contributors: &[String],
exclude_year: bool,
) -> Result<String, Error> {
crate::spdx::parse(license_expression)?;
let notice = copyright.into();
let style = style_override
.unwrap_or_else(|| ResolvedStyle::builtin(detect_style_from_content(content)));
if style.style() == CommentStyle::Uncommentable {
return Err(Error::Io(std::io::Error::new(
std::io::ErrorKind::InvalidData,
"File has no known comment syntax; declare one in \
[[tool.comply.comment-styles]] or use a .license companion",
)));
}
let lines: Vec<&str> = content.lines().collect();
let (span_start, span_end) = header_span(&lines, style.rules());
if span_start != span_end {
if !force {
return Ok(content.to_string());
}
return replace_header_with(
content,
notice,
license_expression,
style,
contributors,
exclude_year,
);
}
generate_with(
notice,
license_expression,
style,
contributors,
exclude_year,
)
.map(|header| insert_header(content, &header))
}
fn preamble_lines(lines: &[&str]) -> usize {
if lines
.first()
.is_some_and(|l| l.starts_with("#!") || l.starts_with("<?xml"))
{
return 1;
}
if lines.first().is_some_and(|l| l.trim_end() == "---") {
if let Some(offset) = lines.iter().skip(1).position(|l| l.trim_end() == "---") {
return offset + 2;
}
}
0
}
fn insert_header(content: &str, header: &str) -> String {
let lines: Vec<&str> = content.lines().collect();
let preamble = preamble_lines(&lines);
if preamble == 0 {
return format!("{header}\n{content}");
}
let mut result = String::new();
for line in &lines[..preamble] {
result.push_str(line);
result.push('\n');
}
result.push('\n');
result.push_str(header);
result.push('\n');
for line in lines[preamble..].iter().skip_while(|l| l.trim().is_empty()) {
result.push_str(line);
result.push('\n');
}
result
}
#[allow(clippy::missing_errors_doc)]
#[allow(clippy::unwrap_used)]
pub fn format_file(
content: &str,
style_override: Option<ResolvedStyle<'_>>,
) -> Result<String, Error> {
let existing_header = detect(content);
if existing_header.is_none() {
return Ok(content.to_string());
}
let existing = existing_header.as_ref().unwrap();
let copyright = existing.copyrights.first().cloned().unwrap_or_default();
let Some(license) = existing.license_expression.clone() else {
return Ok(content.to_string());
};
let style =
style_override.unwrap_or_else(|| ResolvedStyle::builtin(detect_style_from_header(content)));
if style.style() == CommentStyle::Uncommentable {
return Err(Error::Io(std::io::Error::new(
std::io::ErrorKind::InvalidData,
"File has no known comment syntax; declare one in \
[[tool.comply.comment-styles]] or use a .license companion",
)));
}
replace_header(content, ©right, &license, style)
}
fn replace_header(
content: &str,
copyright: &str,
license_expression: &str,
style: ResolvedStyle<'_>,
) -> Result<String, Error> {
replace_header_with(
content,
CopyrightNotice::new(copyright),
license_expression,
style,
&[],
false,
)
}
fn carries_licensing(line: &str, prefixes: &[&str]) -> bool {
const TAGS: [&str; 4] = [
"SPDX-FileCopyrightText:",
"SPDX-SnippetCopyrightText:",
"SPDX-FileContributor:",
"SPDX-License-Identifier:",
];
let trimmed = line.trim_start();
let bare = prefixes
.iter()
.find_map(|prefix| trimmed.strip_prefix(prefix))
.unwrap_or(line);
let stripped = strip_comment_prefix(bare);
TAGS.iter().any(|tag| stripped.starts_with(tag)) || is_plain_copyright_notice(&stripped)
}
fn comment_mask(lines: &[&str], blocks: &[(&str, &str)], prefixes: &[&str]) -> Vec<bool> {
let mut mask = Vec::with_capacity(lines.len());
let mut open = false;
for line in lines {
let trimmed = line.trim();
let opens = blocks.iter().any(|(o, _)| trimmed.starts_with(o));
let closes = blocks.iter().any(|(_, c)| trimmed.ends_with(c));
let configured_line = prefixes.iter().any(|p| trimmed.starts_with(p));
mask.push(open || opens || configured_line || is_comment_line(line));
if opens && !closes {
open = true;
} else if closes {
open = false;
}
}
mask
}
fn is_block_closer(line: &str, blocks: &[(&str, &str)]) -> bool {
let trimmed = line.trim();
blocks.iter().any(|(_, close)| trimmed == *close)
}
fn header_span(lines: &[&str], rules: &[CommentStyleRule]) -> (usize, usize) {
let blocks = block_delimiters(rules);
let prefixes = configured_prefixes(rules);
let in_comment = comment_mask(lines, &blocks, &prefixes);
let sidecar = lines
.iter()
.filter(|l| !l.trim().is_empty())
.all(|l| carries_licensing(l, &prefixes));
let Some(first) = lines
.iter()
.enumerate()
.position(|(i, l)| carries_licensing(l, &prefixes) && (sidecar || in_comment[i]))
else {
return (0, 0);
};
let mut start = first;
if start > 0
&& blocks
.iter()
.any(|(open, _)| lines[start - 1].trim() == *open)
{
start -= 1;
}
let preamble = preamble_lines(lines);
if !sidecar
&& lines[..start]
.iter()
.enumerate()
.any(|(i, l)| i >= preamble && !l.trim().is_empty() && !in_comment[i])
{
return (0, 0);
}
let mut markers: Vec<&str> = leading_comment_marker(lines[first])
.into_iter()
.chain(prefixes.iter().copied())
.collect();
markers.dedup();
let mut last = first;
for (i, line) in lines.iter().enumerate().skip(first) {
if carries_licensing(line, &prefixes) {
last = i;
} else if !(line.trim().is_empty() || is_comment_line_in(line, &markers)) {
break;
}
}
let mut end = last + 1;
if lines.get(end).is_some_and(|l| is_block_closer(l, &blocks)) {
end += 1;
}
(start, end)
}
fn replace_header_with(
content: &str,
notice: CopyrightNotice<'_>,
license_expression: &str,
style: ResolvedStyle<'_>,
contributors: &[String],
exclude_year: bool,
) -> Result<String, Error> {
let lines: Vec<&str> = content.lines().collect();
let (start, end) = header_span(&lines, style.rules());
let new_header = generate_with(
notice,
license_expression,
style,
contributors,
exclude_year,
)?;
let mut result = String::new();
let frontmatter = preamble_lines(&lines);
if frontmatter > 0 && start < frontmatter {
let kept: Vec<&str> = lines[..frontmatter]
.iter()
.enumerate()
.filter(|(i, _)| !(start..end).contains(i))
.map(|(_, line)| *line)
.collect();
for line in kept.iter().take(1) {
result.push_str(line);
result.push('\n');
}
for line in kept.iter().skip(1).skip_while(|l| l.trim().is_empty()) {
result.push_str(line);
result.push('\n');
}
result.push('\n');
result.push_str(&new_header);
result.push('\n');
for line in lines[frontmatter..]
.iter()
.skip_while(|l| l.trim().is_empty())
{
result.push_str(line);
result.push('\n');
}
return Ok(result);
}
let preamble = lines[..start]
.iter()
.rposition(|l| !l.trim().is_empty())
.map_or(0, |i| i + 1);
for line in &lines[..preamble] {
result.push_str(line);
result.push('\n');
}
if preamble > 0 {
result.push('\n');
}
result.push_str(&new_header);
result.push('\n');
for line in lines[end..].iter().skip_while(|l| l.trim().is_empty()) {
result.push_str(line);
result.push('\n');
}
Ok(result)
}
#[cfg(test)]
mod tests {
use super::*;
use crate::header::CopyrightPrefix;
#[test]
fn a_licence_notice_below_real_code_is_not_the_files_header() {
let content = concat!(
"import { createHash } from \"node:crypto\";\n",
"\n",
"/*!\n",
" * Copyright (c) Vendor et al., All rights reserved.\n",
" * SPDX-License-Identifier: BSD-3-Clause\n",
" */\n",
);
let lines: Vec<&str> = content.lines().collect();
assert_eq!(
header_span(&lines, &[]),
(0, 0),
"a vendored notice must be left untouched"
);
}
#[test]
fn a_header_under_a_comment_preamble_is_still_the_files_header() {
let content = concat!(
"// @generated by something\n",
"\n",
"// SPDX-FileCopyrightText: Acme\n",
"// SPDX-License-Identifier: MIT\n",
"\n",
"fn main() {}\n",
);
let lines: Vec<&str> = content.lines().collect();
let (start, end) = header_span(&lines, &[]);
assert!(start < end, "a real header must still be found");
assert!(lines[start].contains("SPDX-FileCopyrightText"), "{start}");
}
fn configured(open: &str, line: &str, close: &str) -> Vec<CommentStyleRule> {
vec![CommentStyleRule {
extensions: vec!["vue".to_string()],
filenames: vec![],
open: open.to_string(),
line: line.to_string(),
close: close.to_string(),
}]
}
#[test]
fn a_configured_style_round_trips_through_annotate() {
for (open, line, close) in [("@@", "", ""), ("<%--", " * ", "--%>")] {
let rules = configured(open, line, close);
let style = ResolvedStyle::new(CommentStyle::Custom(0), &rules);
let once = annotate_file(
"<template></template>\n",
"2026 Acme",
"MIT",
Some(style),
false,
)
.unwrap_or_else(|e| panic!("{open} must annotate: {e}"));
assert!(once.starts_with(open), "{open}: header missing -> {once}");
let twice = annotate_file(&once, "2026 Acme", "MIT", Some(style), false)
.unwrap_or_else(|e| panic!("{open} must re-read: {e}"));
assert_eq!(twice, once, "{open}: its own header was not recognised");
}
}
#[test]
fn a_bang_or_rem_header_round_trips_through_annotate() {
for style in [CommentStyle::Bang, CommentStyle::Rem] {
let once = annotate_file(
"program hello\nend program hello\n",
"2026 Acme",
"MIT",
Some(ResolvedStyle::builtin(style)),
false,
)
.unwrap_or_else(|e| panic!("{style:?} must annotate: {e}"));
let twice = annotate_file(
&once,
"2026 Acme",
"MIT",
Some(ResolvedStyle::builtin(style)),
true,
)
.unwrap_or_else(|e| panic!("{style:?} must re-read: {e}"));
assert_eq!(twice, once, "{style:?}: its own header was not recognised");
assert_eq!(
twice.matches("SPDX-License-Identifier").count(),
1,
"{style:?}: a second header was stacked -> {twice}"
);
}
}
#[test]
fn every_line_style_header_round_trips_through_annotate() {
for style in [
CommentStyle::Slash,
CommentStyle::Hash,
CommentStyle::Dash,
CommentStyle::Semicolon,
CommentStyle::Percent,
CommentStyle::DotDot,
CommentStyle::SlashStar,
CommentStyle::AsteriskParen,
CommentStyle::Html,
] {
let once = annotate_file(
"Title\n=====\n\ntext\n",
"2026 Acme",
"MIT",
Some(ResolvedStyle::builtin(style)),
false,
)
.unwrap_or_else(|e| panic!("{style:?} must annotate: {e}"));
let twice = annotate_file(
&once,
"2026 Acme",
"MIT",
Some(ResolvedStyle::builtin(style)),
true,
)
.unwrap_or_else(|e| panic!("{style:?} must re-read: {e}"));
assert_eq!(twice, once, "{style:?}: its own header was not recognised");
assert_eq!(
twice.matches("SPDX-License-Identifier").count(),
1,
"{style:?}: a second header was stacked -> {twice}"
);
}
}
#[test]
fn a_header_goes_below_an_xml_declaration() {
const DECLARATION: &str = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n";
let style = ResolvedStyle::builtin(CommentStyle::Html);
let annotated = annotate_file(
&format!("{DECLARATION}<root/>\n"),
"2026 X",
"MIT",
Some(style),
false,
)
.expect("must annotate");
assert!(
annotated.starts_with(DECLARATION),
"the declaration must stay on line 1 -> {annotated}"
);
let again = annotate_file(&annotated, "2026 X", "MIT", Some(style), true)
.expect("must rewrite its own header");
assert_eq!(again, annotated, "rewriting moved the declaration");
}
#[test]
fn force_keeps_a_line_that_merely_starts_with_bang_or_rem() {
let cases = [
(
concat!(
"# SPDX-FileCopyrightText: 2019 Original\n",
"#\n",
"# SPDX-License-Identifier: GPL-3.0-only\n",
"REMOTE_URL=https://example.com\n",
"# SPDX-FileContributor: Someone Else\n",
"echo hi\n"
),
"REMOTE_URL=https://example.com",
),
(
concat!(
"# SPDX-FileCopyrightText: 2019 Original\n",
"#\n",
"# SPDX-License-Identifier: GPL-3.0-only\n",
"!important = 1\n",
"# SPDX-FileContributor: Someone Else\n",
"print(\"hi\")\n"
),
"!important = 1",
),
];
for (content, survivor) in cases {
let forced = annotate_file(
content,
"2026 X",
"MIT",
Some(ResolvedStyle::builtin(CommentStyle::Hash)),
true,
)
.expect("must annotate");
assert!(
forced.contains(survivor),
"{survivor} was deleted -> {forced}"
);
}
}
#[test]
fn force_keeps_a_source_line_that_opens_with_a_foreign_marker() {
let cases = [
(
CommentStyle::Html,
concat!(
"<!-- SPDX-FileCopyrightText: 2019 Original -->\n",
"\n",
"* a bullet item\n",
"\n",
"<!-- SPDX-License-Identifier: GPL-3.0-only -->\n",
"\n",
"Prose.\n"
),
"* a bullet item",
),
(
CommentStyle::Slash,
concat!(
"// SPDX-FileCopyrightText: 2019 Original\n",
"\n",
"#include <stdio.h>\n",
"\n",
"// SPDX-License-Identifier: GPL-3.0-only\n",
"\n",
"int main(void) { return 0; }\n"
),
"#include <stdio.h>",
),
(
CommentStyle::Hash,
concat!(
"# SPDX-FileCopyrightText: 2019 Original\n",
"\n",
"---\n",
"\n",
"# SPDX-License-Identifier: GPL-3.0-only\n",
"\n",
"key: value\n"
),
"---",
),
(
CommentStyle::Slash,
concat!(
"// SPDX-FileCopyrightText: 2019 Original\n",
"\n",
";(function(){})()\n",
"\n",
"// SPDX-License-Identifier: GPL-3.0-only\n",
"\n",
"console.log(1)\n"
),
";(function(){})()",
),
(
CommentStyle::Hash,
concat!(
"# SPDX-FileCopyrightText: 2019 Original\n",
"\n",
"%matplotlib inline\n",
"\n",
"# SPDX-License-Identifier: GPL-3.0-only\n",
"\n",
"x = 1\n"
),
"%matplotlib inline",
),
(
CommentStyle::Hash,
concat!(
"# SPDX-FileCopyrightText: 2019 Original\n",
"\n",
"--flag=value\n",
"\n",
"# SPDX-License-Identifier: GPL-3.0-only\n",
"\n",
"echo hi\n"
),
"--flag=value",
),
];
let mut deleted = Vec::new();
for (style, content, survivor) in cases {
let forced = annotate_file(
content,
"2026 X",
"MIT",
Some(ResolvedStyle::builtin(style)),
true,
)
.unwrap_or_else(|e| panic!("{style:?} must annotate: {e}"));
if !forced.contains(survivor) {
deleted.push(survivor);
}
}
assert!(deleted.is_empty(), "deleted by --force: {deleted:?}");
}
#[test]
fn a_header_written_in_another_syntax_is_still_replaced_whole() {
let content = concat!(
"# SPDX-FileCopyrightText: 2001 Old\n",
"#\n",
"# SPDX-License-Identifier: MIT\n",
"\n",
"fn main() {}\n"
);
let out = format_file(content, Some(ResolvedStyle::builtin(CommentStyle::Slash)))
.expect("a header in another syntax is still a header");
assert_eq!(
out.matches("SPDX-License-Identifier").count(),
1,
"exactly one header -- more means the old one survived:\n{out}"
);
assert!(
out.starts_with("// SPDX-FileCopyrightText: 2001 Old\n"),
"the header must be rewritten in place, not stacked:\n{out}"
);
assert!(
!out.contains("# SPDX"),
"no part of the old header may survive:\n{out}"
);
assert!(out.contains("fn main() {}"), "body must survive:\n{out}");
}
#[test]
fn formatting_a_configured_block_header_is_idempotent() {
let rules = configured("<%--", " * ", "--%>");
let style = ResolvedStyle::new(CommentStyle::Custom(0), &rules);
let annotated = annotate_file(
"<template></template>\n",
"2026 Acme",
"MIT",
Some(style),
false,
)
.expect("must annotate");
let formatted = format_file(&annotated, Some(style)).expect("must format");
assert_eq!(formatted, annotated, "format left the old closer behind");
assert_eq!(
formatted.matches("--%>").count(),
1,
"exactly one closer: {formatted}"
);
}
#[test]
fn a_configured_line_style_span_covers_the_whole_header() {
let rules = configured("@@", "", "");
let content =
"@@ SPDX-FileCopyrightText: 2026 Acme\n@@\n@@ SPDX-License-Identifier: MIT\n\nbody\n";
let lines: Vec<&str> = content.lines().collect();
assert_eq!(header_span(&lines, &rules), (0, 3));
}
#[test]
fn a_configured_block_header_is_not_mistaken_for_bare_tags() {
let rules = configured("<%--", " * ", "--%>");
let content = "<%--\n * SPDX-FileCopyrightText: 2026 Acme\n *\n * SPDX-License-Identifier: MIT\n --%>\nbody\n";
let lines: Vec<&str> = content.lines().collect();
let (start, end) = header_span(&lines, &rules);
assert_eq!(
start, 0,
"the opener must be taken from above the first tag"
);
assert!(end > start, "a configured block must register as a header");
}
mod header_must_be_a_comment {
use super::*;
const TEMPLATE: &str = concat!(
"header = \"\"\"\n",
"SPDX-FileCopyrightText: ignorefile contributors\n",
"\n",
"SPDX-License-Identifier: MIT OR Apache-2.0\"\"\"\n",
"name = \"Ignored\"\n"
);
#[test]
fn bare_tags_in_a_string_are_not_a_header_to_replace() {
let out = annotate_file(
TEMPLATE,
"Acme",
"MIT",
Some(ResolvedStyle::builtin(CommentStyle::Hash)),
true,
)
.expect("annotating must succeed");
assert!(
out.contains("SPDX-FileCopyrightText: ignorefile contributors"),
"the template string must survive verbatim, got:\n{out}"
);
assert!(out.contains("name = \"Ignored\""), "got:\n{out}");
assert!(
out.starts_with("# SPDX-FileCopyrightText:"),
"a real header belongs on top instead, got:\n{out}"
);
}
#[test]
fn a_commented_header_is_still_replaced_on_force() {
let content = "# SPDX-FileCopyrightText: 2025 Old\n#\n# SPDX-License-Identifier: Apache-2.0\n\nx = 1\n";
let out = annotate_file(
content,
"2026 New",
"MIT",
Some(ResolvedStyle::builtin(CommentStyle::Hash)),
true,
)
.expect("force must still replace");
assert!(out.contains("2026 New"), "got:\n{out}");
assert!(
!out.contains("2025 Old"),
"the old header must go, got:\n{out}"
);
}
#[test]
fn a_style_override_still_finds_a_block_header_it_does_not_match() {
let content = concat!(
"<!--\n",
"SPDX-FileCopyrightText: 2026 Acme\n",
"\n",
"SPDX-License-Identifier: MIT\n",
"-->\n",
"\n",
"# Doc\n"
);
let out = format_file(content, Some(ResolvedStyle::builtin(CommentStyle::Slash)))
.expect("an override must still locate the block");
assert_eq!(
out.matches("SPDX-License-Identifier").count(),
1,
"exactly one header -- a second means the first was not found:\n{out}"
);
assert!(out.contains("# Doc"), "body must survive:\n{out}");
}
#[test]
fn a_license_companion_of_bare_tags_is_still_a_header() {
let companion = "SPDX-FileCopyrightText: 2026 Acme\nSPDX-License-Identifier: MIT\n";
let detected = detect(companion).expect("a companion is a header");
assert_eq!(detected.license_expression.as_deref(), Some("MIT"));
assert_eq!(detected.copyrights, ["2026 Acme"]);
}
}
mod preamble {
use super::*;
#[test]
fn a_new_header_goes_below_yaml_frontmatter() {
let content = "---\nname: doc\ncreated_by: someone\n---\n\n# Title\n\ntext\n";
let out = annotate_file(
content,
"Acme",
"MIT",
Some(ResolvedStyle::builtin(CommentStyle::Html)),
false,
)
.unwrap();
assert!(
out.starts_with("---\nname: doc\ncreated_by: someone\n---\n"),
"frontmatter has to keep line 1, got:\n{out}"
);
assert!(out.contains("SPDX-License-Identifier: MIT"), "got:\n{out}");
assert!(out.trim_end().ends_with("text"), "body kept, got:\n{out}");
}
#[test]
fn a_new_header_goes_below_a_shebang() {
let content = "#!/bin/sh\necho hi\n";
let out = annotate_file(
content,
"Acme",
"MIT",
Some(ResolvedStyle::builtin(CommentStyle::Hash)),
false,
)
.unwrap();
assert!(
out.starts_with("#!/bin/sh\n"),
"a shebang below line 1 is not a shebang, got:\n{out}"
);
assert!(out.contains("SPDX-License-Identifier: MIT"), "got:\n{out}");
}
#[test]
fn a_header_inside_frontmatter_is_lifted_out_not_rewritten_in_place() {
let content = concat!(
"---\n",
"# SPDX-FileCopyrightText: 2026 Acme\n",
"#\n",
"# SPDX-License-Identifier: MIT\n",
"\n",
"name: doc\n",
"---\n",
"\n",
"# Title\n"
);
let out =
format_file(content, Some(ResolvedStyle::builtin(CommentStyle::Html))).unwrap();
assert!(
out.starts_with("---\nname: doc\n---\n"),
"the frontmatter block must come out intact, got:\n{out}"
);
assert!(
out.contains("SPDX-License-Identifier: MIT"),
"the licensing must survive, got:\n{out}"
);
let block = out
.strip_prefix("---\n")
.and_then(|rest| rest.split_once("\n---\n"))
.map(|(block, _)| block.to_string())
.unwrap_or_default();
assert!(
!block.contains("SPDX") && !block.contains("<!--"),
"frontmatter still holds header text: {block:?}"
);
}
#[test]
fn a_lone_dash_rule_is_not_frontmatter() {
let content = "---\n\nJust a rule, no closing delimiter.\n";
let out = annotate_file(
content,
"Acme",
"MIT",
Some(ResolvedStyle::builtin(CommentStyle::Html)),
false,
)
.unwrap();
assert!(out.starts_with("<!--"), "got:\n{out}");
}
#[test]
fn frontmatter_not_at_the_start_is_left_alone() {
let content = "# Title\n\n---\nname: not-frontmatter\n---\n";
let out = annotate_file(
content,
"Acme",
"MIT",
Some(ResolvedStyle::builtin(CommentStyle::Html)),
false,
)
.unwrap();
assert!(out.starts_with("<!--"), "got:\n{out}");
}
}
mod header_boundary {
use super::*;
const HDR: &str = "# SPDX-FileCopyrightText: 2001 Old\n#\n# SPDX-License-Identifier: MIT\n";
#[test]
fn a_file_carrying_no_licensing_at_all_has_an_empty_span() {
let lines = ["fn main() {}", "// just a comment", "x = 1"];
assert_eq!(header_span(&lines, &[]), (0, 0));
}
#[test]
fn a_shebang_survives_and_keeps_line_one() {
let content = format!("#!/bin/sh\n{HDR}\necho hi\n");
let out =
format_file(&content, Some(ResolvedStyle::builtin(CommentStyle::Hash))).unwrap();
assert!(
out.starts_with("#!/bin/sh\n"),
"the shebang must stay executable, got:\n{out}"
);
assert!(out.contains("echo hi"), "body must survive:\n{out}");
}
#[test]
fn a_preamble_separated_by_a_blank_line_is_preserved() {
let content = format!("# This file is @generated.\n\n{HDR}\nx = 1\n");
let out =
format_file(&content, Some(ResolvedStyle::builtin(CommentStyle::Hash))).unwrap();
assert!(
out.starts_with("# This file is @generated.\n"),
"a blank line separates a preamble from the header, got:\n{out}"
);
}
#[test]
fn a_comment_adjacent_to_the_header_is_still_preserved() {
let content = format!("# adjacent note\n{HDR}\nx = 1\n");
let out =
format_file(&content, Some(ResolvedStyle::builtin(CommentStyle::Hash))).unwrap();
assert!(out.contains("# adjacent note"), "got:\n{out}");
}
#[test]
fn prose_mentioning_an_spdx_tag_is_not_treated_as_one() {
let content =
format!("{HDR}\n# keeps sources SPDX-annotated and clippy-clean.\nx = 1\n");
let out =
format_file(&content, Some(ResolvedStyle::builtin(CommentStyle::Hash))).unwrap();
assert!(
out.contains("SPDX-annotated and clippy-clean"),
"got:\n{out}"
);
}
#[test]
fn a_comment_after_the_header_is_left_alone() {
let content = format!("{HDR}\n# a note about the code below\nx = 1\n");
let out =
format_file(&content, Some(ResolvedStyle::builtin(CommentStyle::Hash))).unwrap();
assert!(
out.contains("# a note about the code below"),
"nothing past the header block may be consumed, got:\n{out}"
);
}
#[test]
fn a_block_comment_header_is_replaced_whole() {
let content = "/*\n * SPDX-FileCopyrightText: 2001 Old\n *\n * SPDX-License-Identifier: MIT\n */\n\nbody {}\n";
let out = format_file(
content,
Some(ResolvedStyle::builtin(CommentStyle::SlashStar)),
)
.unwrap();
assert_eq!(
out.matches("/*").count(),
1,
"the old delimiters must not be left behind, got:\n{out}"
);
assert!(out.contains("body {}"), "got:\n{out}");
}
#[test]
fn a_header_with_no_licence_is_left_untouched() {
let content = "# SPDX-FileCopyrightText: 2001 Old\n\nx = 1\n";
let out =
format_file(content, Some(ResolvedStyle::builtin(CommentStyle::Hash))).unwrap();
assert!(!out.contains("NOASSERTION"), "got:\n{out}");
assert_eq!(out, content, "nothing to canonicalise, so nothing changes");
}
}
#[test]
fn annotating_with_an_unparseable_expression_fails() {
let result = annotate_file_with(
"fn main() {}\n",
"2026 Acme",
"NOT A VALID EXPRESSION",
Some(ResolvedStyle::builtin(CommentStyle::Slash)),
false,
&[],
false,
);
assert!(result.is_err());
}
#[test]
fn reformatting_a_header_whose_expression_is_unparseable_leaves_it_alone() {
let content = concat!(
"// SPDX-FileCopyrightText: 2026 Acme\n",
"// SPDX-License-Identifier: NOT A VALID EXPRESSION\n",
"\n",
"fn main() {}\n"
);
let out = format_file(content, Some(ResolvedStyle::builtin(CommentStyle::Slash)))
.expect("an unparseable tag is reported by lint, not fatal here");
assert!(
out.contains("NOT A VALID EXPRESSION"),
"the author's text must survive verbatim, got:\n{out}"
);
assert!(out.contains("fn main() {}"), "body must survive:\n{out}");
}
#[test]
fn formatting_into_an_uncommentable_style_fails() {
let content = concat!(
"// SPDX-FileCopyrightText: 2026 Acme\n",
"// SPDX-License-Identifier: MIT\n",
"\n",
"fn main() {}\n"
);
let err = format_file(
content,
Some(ResolvedStyle::builtin(CommentStyle::Uncommentable)),
)
.expect_err("a binary format cannot hold a comment");
assert!(
err.to_string().contains("no known comment syntax"),
"got: {err}"
);
}
#[test]
fn format_file_normalizes_slash_style() {
let content = "// SPDX-FileCopyrightText: 2026 Acme Inc\n\
// SPDX-License-Identifier: MIT\n\
\n\
fn main() {}";
let result = format_file(content, None).unwrap();
assert!(result.starts_with("// SPDX-FileCopyrightText: 2026 Acme Inc\n"));
assert!(result.contains("// SPDX-License-Identifier: MIT\n"));
assert!(result.contains("fn main()"));
}
#[test]
fn format_file_normalizes_hash_style() {
let content = "# SPDX-FileCopyrightText: 2026 Acme Inc\n\
# SPDX-License-Identifier: MIT\n\
\n\
def main():\n pass";
let result = format_file(content, None).unwrap();
assert!(result.starts_with("# SPDX-FileCopyrightText: 2026 Acme Inc\n"));
assert!(result.contains("# SPDX-License-Identifier: MIT\n"));
assert!(result.contains("def main()"));
}
#[test]
fn format_file_normalizes_html_style() {
let content = "<!--\n\
SPDX-FileCopyrightText: 2026 Acme Inc\n\
SPDX-License-Identifier: MIT\n\
-->\n\
<html>";
let result = format_file(content, None).unwrap();
assert!(result.starts_with("<!--\n"));
assert!(result.contains("SPDX-FileCopyrightText: 2026 Acme Inc\n"));
assert!(result.contains("SPDX-License-Identifier: MIT\n"));
assert!(result.contains("-->\n"));
assert!(result.contains("<html>"));
}
#[test]
fn format_file_converts_to_canonical_style() {
let content =
"//SPDX-FileCopyrightText:2026 Acme Inc\n//SPDX-License-Identifier:MIT\n\nfn main() {}";
let result = format_file(content, None).unwrap();
assert!(result.starts_with("// SPDX-FileCopyrightText: 2026 Acme Inc\n"));
assert!(result.contains("// SPDX-License-Identifier: MIT\n"));
}
#[test]
fn format_file_preserves_no_header() {
let content = "fn main() {\n println!(\"hello\");\n}\n";
let result = format_file(content, None).unwrap();
assert_eq!(result, content);
}
#[test]
fn format_file_respects_style_override() {
let content = "# SPDX-FileCopyrightText: 2026 Acme Inc\n\
# SPDX-License-Identifier: MIT\n\
\n\
def main():\n pass";
let result =
format_file(content, Some(ResolvedStyle::builtin(CommentStyle::Slash))).unwrap();
assert!(result.starts_with("// SPDX-FileCopyrightText: 2026 Acme Inc\n"));
assert!(result.contains("// SPDX-License-Identifier: MIT\n"));
}
#[test]
fn annotate_new_file_slash_style() {
let content = "fn main() {\n println!(\"hello\");\n}\n";
let result = annotate_file(
content,
"2026 Acme Inc",
"MIT",
Some(ResolvedStyle::builtin(CommentStyle::Slash)),
false,
)
.unwrap();
assert!(result.starts_with("// SPDX-FileCopyrightText: 2026 Acme Inc"));
assert!(result.contains("// SPDX-License-Identifier: MIT"));
assert!(result.contains("fn main()"));
}
#[test]
fn annotate_new_file_hash_style() {
let content = "def main():\n print('hello')\n";
let result = annotate_file(
content,
"2026 Acme Inc",
"MIT",
Some(ResolvedStyle::builtin(CommentStyle::Hash)),
false,
)
.unwrap();
assert!(result.starts_with("# SPDX-FileCopyrightText: 2026 Acme Inc"));
assert!(result.contains("# SPDX-License-Identifier: MIT"));
assert!(result.contains("def main()"));
}
#[test]
fn annotate_new_file_html_style() {
let content = "<html>\n<body>Hello</body>\n</html>\n";
let result = annotate_file(
content,
"2026 Acme Inc",
"MIT",
Some(ResolvedStyle::builtin(CommentStyle::Html)),
false,
)
.unwrap();
assert!(result.starts_with("<!--"));
assert!(result.contains("SPDX-FileCopyrightText: 2026 Acme Inc"));
assert!(result.contains("SPDX-License-Identifier: MIT"));
assert!(result.contains("<html>"));
}
#[test]
fn annotate_existing_header_replaced_when_force() {
let content = "// SPDX-FileCopyrightText: 2025 Old Corp\n\
// SPDX-License-Identifier: Apache-2.0\n\
\n\
fn main() {}";
let result = annotate_file(
content,
"2026 New Corp",
"MIT",
None,
true, )
.unwrap();
assert!(result.contains("2026 New Corp"));
assert!(result.contains("MIT"));
assert!(!result.contains("2025 Old Corp"));
assert!(!result.contains("Apache-2.0"));
assert!(result.contains("fn main()"));
}
#[test]
fn annotate_existing_header_kept_when_no_force() {
let content = "// SPDX-FileCopyrightText: 2025 Old Corp\n\
// SPDX-License-Identifier: Apache-2.0\n\
\n\
fn main() {}";
let result = annotate_file(
content,
"2026 New Corp",
"MIT",
None,
false, )
.unwrap();
assert!(result.contains("2025 Old Corp"));
assert!(result.contains("Apache-2.0"));
assert!(result.contains("fn main()"));
}
#[test]
fn annotate_uncommentable_file_returns_error() {
let result = annotate_file(
"",
"2026 Acme Inc",
"MIT",
Some(ResolvedStyle::builtin(CommentStyle::Uncommentable)),
false,
);
assert!(result.is_err());
}
#[test]
fn annotate_file_with_contributors() {
let content = "fn main() {}\n";
let result = annotate_file_with(
content,
"2026 Acme Inc",
"MIT",
Some(ResolvedStyle::builtin(CommentStyle::Slash)),
false,
&["John Doe".to_string()],
false,
)
.unwrap();
assert!(result.contains("// SPDX-FileCopyrightText: 2026 Acme Inc"));
assert!(result.contains("// SPDX-FileContributor: John Doe"));
assert!(result.contains("// SPDX-License-Identifier: MIT"));
}
#[test]
fn every_prefix_form_is_written_in_the_form_it_names() {
for value in CopyrightPrefix::VALUES {
let prefix: CopyrightPrefix = value.parse().unwrap();
let out = annotate_file(
"fn main() {}\n",
CopyrightNotice::new("2026 Acme").with_prefix(prefix),
"MIT",
Some(ResolvedStyle::builtin(CommentStyle::Slash)),
false,
)
.unwrap();
assert!(
out.contains(&format!("// {}2026 Acme", prefix.tag())),
"`--copyright-prefix {value}` did not render its own form:\n{out}"
);
}
}
#[test]
fn a_header_in_any_prefix_form_is_replaced_rather_than_duplicated() {
for value in CopyrightPrefix::VALUES {
let prefix: CopyrightPrefix = value.parse().unwrap();
let notice = CopyrightNotice::new("2020 First").with_prefix(prefix);
let style = Some(ResolvedStyle::builtin(CommentStyle::Slash));
let once = annotate_file("fn main() {}\n", notice, "MIT", style, false).unwrap();
let twice =
annotate_file(&once, notice.with_text("2021 Second"), "MIT", style, true).unwrap();
assert_eq!(
twice.matches("SPDX-License-Identifier").count(),
1,
"`--copyright-prefix {value}` stacked a second header:\n{twice}"
);
assert!(
twice.contains("2021 Second") && !twice.contains("2020 First"),
"`--copyright-prefix {value}` did not replace the old notice:\n{twice}"
);
}
}
}