test(review): Cover every always-review list lint rule

Splits the lint into a pure lintReviewLists function and a command-line
entry point, and adds a Jest project for scripts with tests for the
pattern matcher, the list format, team names, the CODEOWNERS subset
rule, and entries that match no file the team owns. Lists may now use
an empty include: [] once a team trims every path.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Todd Martin
2026-11-15 12:37:51 -05:00
parent 874ff98a29
commit 8a3b3e6f2b
6 changed files with 442 additions and 92 deletions

View File

@@ -76,6 +76,7 @@ module.exports = {
"<rootDir>/libs/storybook/jest.config.js",
"<rootDir>/libs/legacy-crypto/jest.config.js",
"<rootDir>/libs/managed-settings/jest.config.js",
"<rootDir>/scripts/jest.config.js",
],
// Workaround for a memory leak that crashes tests in CI:

11
scripts/jest.config.js Normal file
View File

@@ -0,0 +1,11 @@
module.exports = {
displayName: "scripts",
preset: "../jest.preset.js",
testEnvironment: "node",
testMatch: ["<rootDir>/*.spec.ts"],
transform: {
"^.+\\.[tj]s$": ["ts-jest", { tsconfig: "<rootDir>/tsconfig.spec.json" }],
},
moduleFileExtensions: ["ts", "js"],
coverageDirectory: "../coverage/scripts",
};

View File

@@ -0,0 +1,297 @@
import { lintReviewLists, ListFile, toRegex } from "./review-lists";
const CODEOWNERS = [
"# Comments and blank lines are skipped.",
"",
"* @bitwarden/team-platform-dev",
"/libs/auth/ @bitwarden/team-auth-dev",
"libs/vault @bitwarden/team-vault-dev # inline comments are skipped",
"/libs/shared/ @bitwarden/team-auth-dev @bitwarden/team-vault-dev",
"/libs/gone/ @bitwarden/team-auth-dev",
"libs/auth/legacy.ts @bitwarden/team-vault-dev",
"apps/cli/src/locales @bitwarden/team-platform-dev",
"apps/cli/src/locales/en/messages.json",
"**/Dockerfile @bitwarden/team-appsec @someone a@example.com",
"docs/*.md @bitwarden/team-docs",
"!negated @bitwarden/team-ghost",
].join("\n");
const TRACKED = [
"README.md",
"libs/auth/login.ts",
"libs/auth/login.spec.ts",
"libs/auth/legacy.ts",
"libs/vault/folder.ts",
"libs/shared/format.ts",
"apps/cli/src/locales/en/messages.json",
"apps/web/Dockerfile",
"docs/guide.md",
"docs/api/ref.md",
];
const HEADER = "# A header comment.\n#\n# Another line.\n\n";
/** Returns a list file for a team with the given body. */
function list(team: string, body: string): ListFile {
return { name: `${team}.yml`, text: HEADER + body };
}
/** Lints the given lists against the fixture CODEOWNERS and tracked files. */
function lint(...lists: ListFile[]): string[] {
return lintReviewLists(CODEOWNERS, lists, TRACKED);
}
describe("toRegex", () => {
it.each([
["*.md", "README.md", true],
["*.md", "docs/guide.md", true],
["Dockerfile", "apps/web/Dockerfile", true],
["/libs/auth/", "libs/auth/login.ts", true],
["/libs/auth/", "apps/libs/auth/login.ts", false],
["libs/auth", "libs/auth/login.ts", true],
["libs/auth", "apps/libs/auth/login.ts", false],
["libs/auth", "libs/auth", true],
["libs/auth/", "libs/auth", false],
["libs/auth.ts", "libs/auth.ts", true],
["libs/auth.ts", "libs/authxts", false],
["docs/*", "docs/guide.md", true],
["docs/*", "docs/api/ref.md", false],
["docs/**", "docs/api/ref.md", true],
["**/Dockerfile", "Dockerfile", true],
["**/Dockerfile", "apps/web/Dockerfile", true],
["apps/**/auth", "apps/web/src/auth/a.ts", true],
["apps/**/auth", "apps/auth/a.ts", true],
["apps/**/auth", "libs/auth/a.ts", false],
["libs/a?.ts", "libs/ab.ts", true],
["libs/a?.ts", "libs/a/b.ts", false],
["*.spec.ts", "libs/auth/login.spec.ts", true],
["*.spec.ts", "libs/auth/login.ts", false],
["libs/a**b.ts", "libs/axyzb.ts", true],
["libs/a**b.ts", "libs/a/b.ts", false],
])("'%s' against '%s' is %s", (pattern, path, expected) => {
expect(toRegex(pattern)!.test(path)).toBe(expected);
});
it.each(["!libs/auth", "libs/[ab]", "libs//auth", "/", ""])(
"rejects unsupported pattern '%s'",
(pattern) => {
expect(toRegex(pattern)).toBeNull();
},
);
});
describe("lintReviewLists", () => {
describe("valid lists", () => {
it("accepts include entries that are the team's own CODEOWNERS lines", () => {
expect(lint(list("team-auth-dev", "include:\n - /libs/auth/\n"))).toEqual([]);
});
it("accepts a subset of the team's lines, not all of them", () => {
expect(lint(list("team-auth-dev", "include:\n - /libs/shared/\n"))).toEqual([]);
});
it("accepts group comments, blank lines, and a comment after a key", () => {
const body =
"include: # always reviewed\n ## Auth ##\n - /libs/auth/\n\n # Shared\n - /libs/shared/\n";
expect(lint(list("team-auth-dev", body))).toEqual([]);
});
it("accepts an exclude that matches some of the team's files", () => {
const body = 'include:\n - /libs/auth/\nexclude:\n - "*.spec.ts"\n';
expect(lint(list("team-auth-dev", body))).toEqual([]);
});
it("accepts an empty include and an empty exclude", () => {
expect(lint(list("team-auth-dev", "include: []\nexclude: []\n"))).toEqual([]);
});
it("accepts double- and single-quoted patterns and compares them without the quotes", () => {
expect(lint(list("team-appsec", 'include:\n - "**/Dockerfile"\n'))).toEqual([]);
expect(lint(list("team-appsec", "include:\n - '**/Dockerfile'\n"))).toEqual([]);
});
it("counts a co-owned line for each of its owners", () => {
expect(
lint(
list("team-auth-dev", "include:\n - /libs/shared/\n"),
list("team-vault-dev", "include:\n - /libs/shared/\n"),
),
).toEqual([]);
});
it("ignores files in .github/review that aren't lists", () => {
expect(lint({ name: "README.md", text: "not a list" })).toEqual([]);
});
it("accepts no lists at all", () => {
expect(lint()).toEqual([]);
});
});
describe("format", () => {
it("reports a missing include key", () => {
expect(lint(list("team-auth-dev", 'exclude:\n - "*.spec.ts"\n'))).toEqual([
".github/review/team-auth-dev.yml: missing the required include key.",
]);
});
it("reports an unknown key and the items under it", () => {
expect(lint(list("team-auth-dev", "include: []\nowners:\n - /libs/auth/\n"))).toEqual([
".github/review/team-auth-dev.yml:6 unknown key 'owners'. Only include and exclude are allowed.",
".github/review/team-auth-dev.yml:7 expected '- <pattern>' under include or exclude.",
]);
});
it("reports a duplicate key", () => {
expect(lint(list("team-auth-dev", "include: []\ninclude: []\n"))).toEqual([
".github/review/team-auth-dev.yml:6 duplicate key 'include'.",
]);
});
it("reports an item before any key", () => {
expect(lint(list("team-auth-dev", " - /libs/auth/\ninclude: []\n"))).toEqual([
".github/review/team-auth-dev.yml:5 expected '- <pattern>' under include or exclude.",
]);
});
it("reports an item after an empty [] value", () => {
expect(lint(list("team-auth-dev", "include: []\n - /libs/auth/\n"))).toEqual([
".github/review/team-auth-dev.yml:6 expected '- <pattern>' under include or exclude.",
]);
});
it("reports a line that isn't a key, an item, or a comment", () => {
expect(lint(list("team-auth-dev", "include:\n /libs/auth/\ninclude-ish\n"))).toEqual([
".github/review/team-auth-dev.yml:6 expected '- <pattern>' under include or exclude.",
".github/review/team-auth-dev.yml:7 expected '- <pattern>' under include or exclude.",
]);
});
it("reports an inline value on a key", () => {
expect(lint(list("team-auth-dev", "include: /libs/auth/\n"))).toEqual([
".github/review/team-auth-dev.yml:5 expected '- <pattern>' under include or exclude.",
".github/review/team-auth-dev.yml: missing the required include key.",
]);
});
it.each([
["*.spec.ts", "starts with *"],
["libs/auth #legacy", "contains ' #'"],
["libs: auth", "contains ': '"],
])("reports unquoted '%s', which %s", (pattern) => {
expect(
lint(list("team-auth-dev", `include:\n - /libs/auth/\nexclude:\n - ${pattern}\n`)),
).toEqual([
`.github/review/team-auth-dev.yml:8 quote '${pattern}'. YAML reads it differently unquoted.`,
]);
});
});
describe("teams", () => {
it("reports a list whose team CODEOWNERS doesn't name", () => {
expect(lint(list("team-unknown", "include: []\n"))).toEqual([
".github/review/team-unknown.yml: @bitwarden/team-unknown is not a team in CODEOWNERS.",
]);
});
it("reports a list for a team named only on a line GitHub skips", () => {
expect(lint(list("team-ghost", "include: []\n"))).toEqual([
".github/review/team-ghost.yml: @bitwarden/team-ghost is not a team in CODEOWNERS.",
]);
});
it("reports a list for a user or email owner, which isn't a team", () => {
expect(lint(list("someone", "include: []\n"))).toEqual([
".github/review/someone.yml: @bitwarden/someone is not a team in CODEOWNERS.",
]);
});
});
describe("include entries must be the team's CODEOWNERS lines", () => {
it("reports an entry that isn't a CODEOWNERS line", () => {
expect(lint(list("team-auth-dev", "include:\n - libs/auth/login.ts\n"))).toEqual([
".github/review/team-auth-dev.yml:6 include 'libs/auth/login.ts' is not a CODEOWNERS line for @bitwarden/team-auth-dev.",
]);
});
it("reports another team's CODEOWNERS line", () => {
expect(lint(list("team-auth-dev", "include:\n - libs/vault\n"))).toEqual([
".github/review/team-auth-dev.yml:6 include 'libs/vault' is not a CODEOWNERS line for @bitwarden/team-auth-dev.",
]);
});
it("reports the team's line written differently, even when it matches the same files", () => {
expect(lint(list("team-auth-dev", "include:\n - libs/auth\n"))).toEqual([
".github/review/team-auth-dev.yml:6 include 'libs/auth' is not a CODEOWNERS line for @bitwarden/team-auth-dev.",
]);
});
});
describe("entries must match a file the team owns", () => {
it("reports an include line that matches no tracked file", () => {
expect(lint(list("team-auth-dev", "include:\n - /libs/gone/\n"))).toEqual([
".github/review/team-auth-dev.yml:6 include '/libs/gone/' matches no file @bitwarden/team-auth-dev owns, so it has no effect.",
]);
});
it("reports an include line a later line gives to no owner", () => {
expect(lint(list("team-platform-dev", "include:\n - apps/cli/src/locales\n"))).toEqual([
".github/review/team-platform-dev.yml:6 include 'apps/cli/src/locales' matches no file @bitwarden/team-platform-dev owns, so it has no effect.",
]);
});
it("accepts a line a later line overrides only in part", () => {
expect(lint(list("team-vault-dev", "include:\n - libs/auth/legacy.ts\n"))).toEqual([]);
expect(lint(list("team-auth-dev", "include:\n - /libs/auth/\n"))).toEqual([]);
});
it("reports an include line a later line gives entirely to another team", () => {
const codeowners = `${CODEOWNERS}\n/libs/auth/ @bitwarden/team-vault-dev`;
expect(
lintReviewLists(
codeowners,
[list("team-auth-dev", "include:\n - /libs/auth/\n")],
TRACKED,
),
).toEqual([
".github/review/team-auth-dev.yml:6 include '/libs/auth/' matches no file @bitwarden/team-auth-dev owns, so it has no effect.",
]);
});
it("reports an exclude that matches only another team's files", () => {
expect(lint(list("team-auth-dev", "include: []\nexclude:\n - libs/vault\n"))).toEqual([
".github/review/team-auth-dev.yml:7 exclude 'libs/vault' matches no file @bitwarden/team-auth-dev owns, so it has no effect.",
]);
});
it("reports an exclude that matches no tracked file", () => {
expect(lint(list("team-auth-dev", 'include: []\nexclude:\n - "*.go"\n'))).toEqual([
".github/review/team-auth-dev.yml:7 exclude '*.go' matches no file @bitwarden/team-auth-dev owns, so it has no effect.",
]);
});
it.each(["!libs/auth", "libs/[ab]"])(
"reports an exclude with unsupported syntax '%s'",
(pattern) => {
expect(lint(list("team-auth-dev", `include: []\nexclude:\n - ${pattern}\n`))).toEqual([
`.github/review/team-auth-dev.yml:7 '${pattern}' is not a valid CODEOWNERS pattern.`,
]);
},
);
});
it("reports every problem across every list, with file and line", () => {
expect(
lint(
list("team-auth-dev", "include:\n - /libs/auth/\n - libs/vault\n - /libs/gone/\n"),
list("team-unknown", "include: []\n"),
list("team-vault-dev", "exclude: []\n"),
),
).toEqual([
".github/review/team-auth-dev.yml:7 include 'libs/vault' is not a CODEOWNERS line for @bitwarden/team-auth-dev.",
".github/review/team-auth-dev.yml:8 include '/libs/gone/' matches no file @bitwarden/team-auth-dev owns, so it has no effect.",
".github/review/team-unknown.yml: @bitwarden/team-unknown is not a team in CODEOWNERS.",
".github/review/team-vault-dev.yml: missing the required include key.",
]);
});
});

View File

@@ -13,10 +13,14 @@ import { execFileSync } from "child_process";
import fs from "fs";
import path from "path";
const repoRoot = path.join(__dirname, "..", "..");
const reviewDir = path.join(repoRoot, ".github", "review");
const codeownersPath = path.join(repoRoot, ".github", "CODEOWNERS");
const ORG = "@bitwarden/";
const REVIEW_DIR = ".github/review";
export interface ListFile {
/// The file name in .github/review, such as `team-auth-dev.yml`.
name: string;
text: string;
}
interface Rule {
pattern: string;
@@ -30,11 +34,9 @@ interface Entry {
line: number;
}
const errors: string[] = [];
/// Compiles a CODEOWNERS pattern to a regular expression over repository paths, following
/// GitHub's CODEOWNERS rules. Returns null for syntax GitHub doesn't support.
function toRegex(source: string): RegExp | null {
export function toRegex(source: string): RegExp | null {
if (source.startsWith("!") || /[[\]]/.test(source)) {
return null;
}
@@ -91,10 +93,11 @@ function toRegex(source: string): RegExp | null {
return new RegExp(re);
}
/// Reads the CODEOWNERS rules in order, with the teams each line names.
function readCodeowners(): Rule[] {
/// Reads the CODEOWNERS rules in order, with the teams each line names. Skips lines GitHub
/// skips: comments, blank lines, and patterns it doesn't support.
function readCodeowners(text: string): Rule[] {
const rules: Rule[] = [];
for (const raw of fs.readFileSync(codeownersPath, "utf8").split(/\r?\n/)) {
for (const raw of text.split(/\r?\n/)) {
const [pattern, ...owners] = raw
.replace(/\s#.*$/, "")
.trim()
@@ -112,51 +115,56 @@ function readCodeowners(): Rule[] {
return rules;
}
/// Parses a list strictly. `file` is relative to the repository root. Accepts comments, blank lines, the `include` and `exclude` keys, and
/// `- pattern` items under them. Anything else is an error, so a list can't hold a key or value
/// that YAML would read differently from what it looks like.
function readList(file: string): Entry[] {
/// Parses a list strictly. Accepts comments, blank lines, the `include` and `exclude` keys, an
/// empty `[]` value, and `- pattern` items under a key. Anything else is an error, so a list can't
/// hold a key or value that YAML would read differently from what it looks like.
function readList(file: string, text: string, errors: string[]): Entry[] {
const entries: Entry[] = [];
const seen = new Set<string>();
let key: Entry["key"] | null = null;
fs.readFileSync(path.join(repoRoot, file), "utf8")
.split(/\r?\n/)
.forEach((raw, index) => {
const line = index + 1;
const text = raw.trim();
if (text === "" || text.startsWith("#")) {
text.split(/\r?\n/).forEach((raw, index) => {
const line = index + 1;
const trimmed = raw.trim();
if (trimmed === "" || trimmed.startsWith("#")) {
return;
}
const keyMatch = raw.match(/^(\w+):\s*(\[\])?\s*(?:#.*)?$/);
if (keyMatch) {
if (keyMatch[1] !== "include" && keyMatch[1] !== "exclude") {
errors.push(
`${file}:${line} unknown key '${keyMatch[1]}'. Only include and exclude are allowed.`,
);
key = null;
return;
}
const keyMatch = raw.match(/^(\w+):\s*(?:#.*)?$/);
if (keyMatch) {
if (keyMatch[1] !== "include" && keyMatch[1] !== "exclude") {
errors.push(
`${file}:${line} unknown key '${keyMatch[1]}'. Only include and exclude are allowed.`,
);
key = null;
return;
}
key = keyMatch[1];
seen.add(key);
return;
if (seen.has(keyMatch[1])) {
errors.push(`${file}:${line} duplicate key '${keyMatch[1]}'.`);
}
const itemMatch = raw.match(/^\s+-\s+(.+?)\s*$/);
if (!itemMatch || key === null) {
errors.push(`${file}:${line} expected '- <pattern>' under include or exclude.`);
return;
key = keyMatch[1];
seen.add(key);
// An empty `[]` value takes no items.
if (keyMatch[2]) {
key = null;
}
const value = itemMatch[1];
const quoted = value.match(/^"(.*)"$/) ?? value.match(/^'(.*)'$/);
const startsWithWildcard = value.startsWith("*");
const containsYamlSyntax = /\s#|:\s/.test(value);
const needsQuotes = startsWithWildcard || containsYamlSyntax;
if (!quoted && needsQuotes) {
errors.push(`${file}:${line} quote '${value}'. YAML reads it differently unquoted.`);
return;
}
entries.push({ key, pattern: quoted ? quoted[1] : value, line });
});
return;
}
const itemMatch = raw.match(/^\s+-\s+(.+?)\s*$/);
if (!itemMatch || key === null) {
errors.push(`${file}:${line} expected '- <pattern>' under include or exclude.`);
return;
}
const value = itemMatch[1];
const quoted = value.match(/^"(.*)"$/) ?? value.match(/^'(.*)'$/);
const startsWithWildcard = value.startsWith("*");
const containsYamlSyntax = /\s#|:\s/.test(value);
const needsQuotes = startsWithWildcard || containsYamlSyntax;
if (!quoted && needsQuotes) {
errors.push(`${file}:${line} quote '${value}'. YAML reads it differently unquoted.`);
return;
}
entries.push({ key, pattern: quoted ? quoted[1] : value, line });
});
if (!seen.has("include")) {
errors.push(`${file}: missing the required include key.`);
@@ -164,59 +172,81 @@ function readList(file: string): Entry[] {
return entries;
}
const rules = readCodeowners();
const trackedFiles = execFileSync("git", ["-C", repoRoot, "ls-files", "-z"], { encoding: "utf8" })
.split("\0")
.filter((f) => f !== "");
/// Checks every list against CODEOWNERS and the tracked files. Returns one message per problem,
/// or none when every list matches.
export function lintReviewLists(
codeowners: string,
lists: ListFile[],
trackedFiles: string[],
): string[] {
const errors: string[] = [];
const rules = readCodeowners(codeowners);
// Each file's owning teams come from the last CODEOWNERS line that matches it, as on GitHub.
const ownersOf = new Map<string, string[]>();
for (const file of trackedFiles) {
let teams: string[] = [];
for (const rule of rules) {
if (rule.regex.test(file)) {
teams = rule.teams;
// Each file's owning teams come from the last CODEOWNERS line that matches it, as on GitHub.
const ownersOf = new Map<string, string[]>();
for (const file of trackedFiles) {
let teams: string[] = [];
for (const rule of rules) {
if (rule.regex.test(file)) {
teams = rule.teams;
}
}
}
ownersOf.set(file, teams);
}
const listFiles = fs.readdirSync(reviewDir).filter((f) => f.endsWith(".yml"));
for (const name of listFiles) {
const team = name.slice(0, -".yml".length);
const file = path.relative(repoRoot, path.join(reviewDir, name));
const ownLines = new Set(rules.filter((r) => r.teams.includes(team)).map((r) => r.pattern));
if (ownLines.size === 0) {
errors.push(`${file}: ${ORG}${team} is not a team in CODEOWNERS.`);
continue;
ownersOf.set(file, teams);
}
for (const entry of readList(file)) {
const where = `${file}:${entry.line}`;
if (entry.key === "include" && !ownLines.has(entry.pattern)) {
errors.push(
`${where} include '${entry.pattern}' is not a CODEOWNERS line for ${ORG}${team}.`,
);
for (const list of lists.filter((l) => l.name.endsWith(".yml"))) {
const team = list.name.slice(0, -".yml".length);
const file = `${REVIEW_DIR}/${list.name}`;
const ownLines = new Set(rules.filter((r) => r.teams.includes(team)).map((r) => r.pattern));
if (ownLines.size === 0) {
errors.push(`${file}: ${ORG}${team} is not a team in CODEOWNERS.`);
continue;
}
const regex = toRegex(entry.pattern);
if (regex === null) {
errors.push(`${where} '${entry.pattern}' is not a valid CODEOWNERS pattern.`);
continue;
}
const matched = trackedFiles.filter((f) => regex.test(f));
if (!matched.some((f) => ownersOf.get(f)?.includes(team))) {
errors.push(
`${where} ${entry.key} '${entry.pattern}' matches no file ${ORG}${team} owns, so it has no effect.`,
);
for (const entry of readList(file, list.text, errors)) {
const where = `${file}:${entry.line}`;
if (entry.key === "include" && !ownLines.has(entry.pattern)) {
errors.push(
`${where} include '${entry.pattern}' is not a CODEOWNERS line for ${ORG}${team}.`,
);
continue;
}
const regex = toRegex(entry.pattern);
if (regex === null) {
errors.push(`${where} '${entry.pattern}' is not a valid CODEOWNERS pattern.`);
continue;
}
const matched = trackedFiles.filter((f) => regex.test(f));
if (!matched.some((f) => ownersOf.get(f)?.includes(team))) {
errors.push(
`${where} ${entry.key} '${entry.pattern}' matches no file ${ORG}${team} owns, so it has no effect.`,
);
}
}
}
return errors;
}
if (errors.length > 0) {
console.error("Always-review lists don't match CODEOWNERS:");
console.error(errors.join("\n"));
process.exit(1);
}
if (require.main === module) {
const repoRoot = path.join(__dirname, "..", "..");
const reviewDir = path.join(repoRoot, REVIEW_DIR);
const lists = fs
.readdirSync(reviewDir)
.map((name) => ({ name, text: fs.readFileSync(path.join(reviewDir, name), "utf8") }));
const trackedFiles = execFileSync("git", ["-C", repoRoot, "ls-files", "-z"], {
encoding: "utf8",
})
.split("\0")
.filter((f) => f !== "");
const codeowners = fs.readFileSync(path.join(repoRoot, ".github", "CODEOWNERS"), "utf8");
console.log(`All ${listFiles.length} always-review lists match CODEOWNERS.`);
const errors = lintReviewLists(codeowners, lists, trackedFiles);
if (errors.length > 0) {
console.error("Always-review lists don't match CODEOWNERS:");
console.error(errors.join("\n"));
process.exit(1);
}
console.log(
`All ${lists.filter((l) => l.name.endsWith(".yml")).length} always-review lists match CODEOWNERS.`,
);
}

View File

@@ -6,5 +6,6 @@
"moduleResolution": "NodeNext",
"target": "ESNext"
},
"include": ["*.ts"]
"include": ["*.ts"],
"exclude": ["*.spec.ts"]
}

View File

@@ -0,0 +1,10 @@
{
"extends": "./tsconfig.json",
"compilerOptions": {
"module": "commonjs",
"moduleResolution": "node10",
"types": ["jest", "node"]
},
"include": ["*.spec.ts", "*.ts"],
"exclude": []
}