feat(naming): widen the Roblox allowed-words list to members and trailing capitals (#664)

* fix(naming): allow Roblox names that end in a capital

The filter tested each name in isolation, but the failure mode is the
name embedded in a longer identifier. Motor6D holds no pair of its own,
so it was dropped - yet targetMotor6DPart, motor6DWeld and Motor6DConfig
all error, because the trailing D lands against the next word's capital.

Adds a trailing-capital arm to the predicate, which picks up Motor6D,
Path2D, Path3D, RotateP and RotateV, and lets Path2D absorb
Path2DControlPoint. 67 words -> 71.

Word-initial position is still uncovered: matching is case-sensitive and
strictCamelCase lowercases the first word, so motor6DWeld stays an error
while targetMotor6DPart passes. Same limitation flawless documents for
cframeGoal. Noted in the README.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* feat(naming): scrape member names for the allowed-words list

The list was built from declared type names only, on the reasoning that
members are reached as property accesses and never declared. That holds
for enum items but not for properties: a variable is as likely to be
named after the property it holds as after a type, and no type is called
ZIndex, so autoZIndex stayed an error. ZIndexBehavior was in the list,
but a word has to match literally, and autoZIndex does not contain it.

Scrapes interface members from roblox.d.ts and None.d.ts. Enum items stay
out - Enum.TextXAlignment.Center really is only ever an access. 71 words
-> 171, and ZIndex now absorbs ZIndexBehavior.

Members also drag in bare capitals (Vector3.X and friends), which qualify
under the trailing-capital arm. They are inert rather than dangerous -
folding only lowercases a word's tail and a single capital has none, so
applyAllowedWords returns the name unchanged - but nothing could ever
prune them, so needsAllowing now rejects anything shorter than two
characters.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(naming): drop method names from the allowed-words list

The member scrape took every member, so `Color3.ToHSV` put `ToHSV` in the
list and `colorToHSV` became a legal variable. A property lends its
spelling to whatever holds it, which is the whole reason to scrape
members, but a call spells the API out at the call site, where no naming
rule applies. `toHsv` is the name to want.

Restricts the member pattern to data properties. All three declaration
forms count as a method - `ToHSV(this: Color3): T`, `Name<T>(value: T): T`
and `toHSV: (color: Color3) => T` - and the last needs the lookahead to
skip its own whitespace, since a negative lookahead after `\s*` backtracks
to zero width and then tests the space rather than the `(`.

171 words -> 139, all 32 of them function-only. Nothing was masking a
property during pruning, so no word comes back.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* feat(deps): take the flawless 1.9.0 word-initial fix

`allowedWords` matched case-sensitively, so a word never matched at the
start of a name: `targetMotor6DPart` passed but `motor6DWeld` did not.
flawless 1.9.0 matches the lowercased-initial form at index 0, which is
the only spelling `strictCamelCase` permits there.

Mirrors the change in the generator's copy of `applyAllowedWords`, which
prunes the list by asking the question the rule will ask. The output is
unchanged at 139 words - nothing in `@rbxts/types` was being kept only
because index 0 could not match. Drops the README caveat.

`pnpm gen` also picks up `flawless/no-shared-mocks`, new in the bump and
not enabled here.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: christopher-buss

README.md

@@ -793,9 +793,16 @@ export default isentinel({
 ```ts
 const targetCFrame = new CFrame(); // ok
 const listLayoutUIPadding = 0; // ok
+const autoZIndex = 0; // ok - properties count, not just types
 const target_CFrame = 0; // still an error
+const fooXYBar = 0; // still an error - not a Roblox name
+const colorToHSV = 0; // still an error - methods do not count, use `colorToHsv`
 ```
 
+The generated list covers type names and data properties, not methods. A call
+spells the API out at the call site, where the naming rules do not reach, so
+`Color3.ToHSV` is no reason to let the variable holding its result skip them.
+
 Pass an array to use exactly those words instead. Spread `ROBLOX_ALLOWED_WORDS`
 to extend the list rather than replace it:
 
@@ -814,6 +821,11 @@ selector opts out with its own `allowedWords: []`. Only the two strict formats
 honour it, so it can never loosen `snake_case` or `UPPER_CASE`, and a word only
 matches at a hump boundary, so it cannot split an existing hump.
 
+At the **start** of a `strictCamelCase` name a word also matches with its first
+character lowercased, since that is the only spelling the format allows there —
+`motor6DWeld` and `targetMotor6DPart` both pass. Everywhere else the word has to
+be spelled as the API spells it, so `targetmotor6DPart` is still an error.
+
 #### Oxlint
 
 The config can run alongside (or be replaced by)

pnpm-lock.yaml

@@ -90,7 +90,7 @@ catalogs:
     eslint-plugin-better-max-params: 1.0.0
     eslint-plugin-comment-length: 2.3.1
     eslint-plugin-de-morgan: 2.1.3
-    eslint-plugin-flawless: 1.7.0
+    eslint-plugin-flawless: 1.9.0
     eslint-plugin-format-lua: 2.0.0
     eslint-plugin-import-lite: 0.6.0
     eslint-plugin-jsdoc: 63.2.2

pnpm-workspace.yaml

@@ -21,6 +21,15 @@ const SOURCES = [
 	"include/generated/enums.d.ts",
 ];
 
+/**
+ * The sources whose properties are worth scraping as well as their type names.
+ *
+ * A property is as likely to name a variable as the type is - `autoZIndex`
+ * holds a `ZIndex`, and no type is called `ZIndex`. Enum items are excluded:
+ * they are only ever reached as `Enum.TextXAlignment.Center`, never declared.
+ */
+const MEMBER_SOURCES = ["include/roblox.d.ts", "include/generated/None.d.ts"];
+
 /**
  * `declare const CFrame: CFrameConstructor` - the datatype values.
  */
@@ -37,18 +46,40 @@ const TOP_LEVEL_INTERFACE = /^interface (\w+)/gmu;
  */
 const ENUM_NAMESPACE = /^[\t ]*export namespace (\w+)/gmu;
 
+/**
+ * `ZIndex: number` - the data properties declared inside an interface, which
+ * the leading indent distinguishes from the interface itself.
+ *
+ * Methods are deliberately excluded. A property lends its spelling to whatever
+ * holds it, but a call is written out at the call site, where the API spelling
+ * is already required and no naming rule applies - so `Color3.ToHSV` is no
+ * reason to let a variable be called `toHSV`, and `toHsv` is the name to use.
+ * All three declaration forms count as a method: `ToHSV(this: Color3): T`,
+ * `Name<T>(value: T): T`, and `toHSV: (color: Color3) => T`. The lookahead
+ * does its own whitespace skip, because a negative lookahead after `\s*` would
+ * backtrack to zero width and then test the space rather than the `(`.
+ */
+const INTERFACE_MEMBER = /^[\t ]+(?:readonly )?(\w+)\??\s*:(?=\s*[^\s(<])/gmu;
+
 const CONSECUTIVE_CAPITALS = /[A-Z]{2}/u;
 
+/**
+ * A name ending in a capital is only a problem once something follows it, and
+ * in either strict format the next word starts with a capital - `Motor6D` is
+ * fine on its own but `motor6DWeld` is not.
+ */
+const TRAILING_CAPITAL = /[A-Z]$/u;
+
 /**
  * The Roblox names a `strictCamelCase` / `StrictPascalCase` identifier cannot
  * spell without an escape.
  *
- * Only names holding two capitals in a row need listing - those are the only
- * ones the strict formats reject - which turns the ~1500 declared names into
- * around 80. The list is then pruned: a name is dropped when the words already
- * kept resolve it anyway, so `CFrame` absorbs `CFrameValue`,
- * `CFrameConstructor` and `UserCFrame`, and `UDim` absorbs `UDim2`. Candidates
- * are visited shortest-first so the more general word is always the one kept.
+ * Only names that can put two capitals in a row need listing, which turns the
+ * ~7000 declared names and members into a few hundred. The list is then pruned:
+ * a name is dropped when the words already kept resolve it anyway, so `CFrame`
+ * absorbs `CFrameValue`, `CFrameConstructor` and `UserCFrame`, `UDim` absorbs
+ * `UDim2`, and `ZIndex` absorbs `ZIndexBehavior`. Candidates are visited
+ * shortest-first so the more general word is always the one kept.
  *
  * Comparisons are by code unit rather than `localeCompare`, so the output does
  * not depend on the host locale.
@@ -58,13 +89,13 @@ const CONSECUTIVE_CAPITALS = /[A-Z]{2}/u;
 export async function deriveRobloxAllowedWords(): Promise<Array<string>> {
 	const declared = await readDeclaredNames();
 	const candidates = [...declared]
-		.filter((name) => CONSECUTIVE_CAPITALS.test(name))
+		.filter((name) => needsAllowing(name))
 		.sort((left, right) => left.length - right.length || (left < right ? -1 : 1));
 
 	const kept: Array<string> = [];
 	for (const candidate of candidates) {
 		const longestFirst = kept.toSorted((left, right) => right.length - left.length);
-		if (CONSECUTIVE_CAPITALS.test(applyAllowedWords(candidate, longestFirst))) {
+		if (needsAllowing(applyAllowedWords(candidate, longestFirst))) {
 			kept.push(candidate);
 		}
 	}
@@ -83,11 +114,24 @@ function isUppercaseCharacter(character: string): boolean {
 	return character >= "A" && character <= "Z";
 }
 
+/**
+ * The word with its first character lowercased, which is how a word reads at
+ * the start of a `strictCamelCase` name.
+ *
+ * @param word - The word in its API spelling.
+ * @returns The word with a lowercase first character.
+ */
+function lowercaseInitial(word: string): string {
+	return word.slice(0, 1).toLowerCase() + word.slice(1);
+}
+
 /**
  * The longest allowed word starting at `index`, if that position opens a hump.
  *
  * A word only matches at the start of the name or after a character that is not
- * uppercase, so it can never split an existing hump.
+ * uppercase, so it can never split an existing hump. At the start the word also
+ * matches in its lowercased-initial form, because that is the only spelling
+ * `strictCamelCase` permits there - `motor6DWeld` holds `Motor6D`.
  *
  * @param name - The name being rewritten.
  * @param allowedWords - The words to look for, longest first.
@@ -99,8 +143,13 @@ function findWordAt(
 	allowedWords: ReadonlyArray<string>,
 	index: number,
 ): string | undefined {
-	const previous = index === 0 ? undefined : name[index - 1];
-	if (previous !== undefined && isUppercaseCharacter(previous)) {
+	if (index === 0) {
+		return allowedWords.find((candidate) => {
+			return name.startsWith(candidate) || name.startsWith(lowercaseInitial(candidate));
+		});
+	}
+
+	if (isUppercaseCharacter(name[index - 1] ?? "")) {
 		return undefined;
 	}
 
@@ -132,34 +181,87 @@ function applyAllowedWords(name: string, allowedWords: ReadonlyArray<string>): s
 			continue;
 		}
 
-		result += word[0] + word.slice(1).toLowerCase();
+		result += name.startsWith(word, index)
+			? word.slice(0, 1) + word.slice(1).toLowerCase()
+			: word.toLowerCase();
 		index += word.length;
 	}
 
 	return result;
 }
 
 /**
- * Reads every declared name out of the `@rbxts/types` sources.
+ * Whether a name can put two capitals in a row, which is what the strict
+ * formats reject.
+ *
+ * Two ways to get there: the name already holds a pair (`CFrame`), or it ends
+ * in a capital and so collides with whatever word follows it in an identifier
+ * (`Motor6D` in `motor6DWeld`). Checking the name in isolation catches only the
+ * first.
  *
- * @returns The union of datatype, Instance and enum names.
+ * @param name - The name to test.
+ * @returns True when the name needs to be in the list.
+ */
+function needsAllowing(name: string): boolean {
+	// A one-character word folds to itself - `applyAllowedWords` only lowercases
+	// a word's tail, and a single capital has none - so listing `X` can never
+	// change an outcome. Members like `Vector3.X` would otherwise qualify under
+	// the trailing-capital arm and sit in the list doing nothing.
+	if (name.length < 2) {
+		return false;
+	}
+
+	return CONSECUTIVE_CAPITALS.test(name) || TRAILING_CAPITAL.test(name);
+}
+
+/**
+ * Adds every capture of every pattern to `names`.
+ *
+ * @param content - The file to scan.
+ * @param patterns - The global-flagged patterns to run, each capturing a name.
+ * @param names - The set to add to.
+ */
+function collectNames(content: string, patterns: Array<RegExp>, names: Set<string>): void {
+	for (const pattern of patterns) {
+		for (const [, name] of content.matchAll(pattern)) {
+			if (name !== undefined) {
+				names.add(name);
+			}
+		}
+	}
+}
+
+/**
+ * Reads one `@rbxts/types` source.
+ *
+ * @param root - The resolved package root.
+ * @param source - The path within the package.
+ * @returns The file contents.
+ */
+async function readSource(root: string, source: string): Promise<string> {
+	return fs.readFile(path.join(root, source), "utf8");
+}
+
+/**
+ * Reads every name an identifier can be built from out of `@rbxts/types`.
+ *
+ * @returns The union of datatype, Instance, enum and member names.
  */
 async function readDeclaredNames(): Promise<Set<string>> {
 	const require = createRequire(import.meta.url);
 	const root = path.dirname(require.resolve("@rbxts/types/package.json"));
-	const contents = await Promise.all(
-		SOURCES.map(async (source) => fs.readFile(path.join(root, source), "utf8")),
-	);
+	const [typeSources, memberSources] = await Promise.all([
+		Promise.all(SOURCES.map(async (source) => readSource(root, source))),
+		Promise.all(MEMBER_SOURCES.map(async (source) => readSource(root, source))),
+	]);
 
 	const names = new Set<string>();
-	for (const content of contents) {
-		for (const pattern of [DECLARE_CONST, TOP_LEVEL_INTERFACE, ENUM_NAMESPACE]) {
-			for (const [, name] of content.matchAll(pattern)) {
-				if (name !== undefined) {
-					names.add(name);
-				}
-			}
-		}
+	for (const content of typeSources) {
+		collectNames(content, [DECLARE_CONST, TOP_LEVEL_INTERFACE, ENUM_NAMESPACE], names);
+	}
+
+	for (const content of memberSources) {
+		collectNames(content, [INTERFACE_MEMBER], names);
 	}
 
 	return names;

scripts/roblox-allowed-words-shared.ts

@@ -128,6 +128,7 @@ export const jsPluginRuleNames: ReadonlySet<string> = new Set([
 	"flawless/no-export-default-arrow",
 	"flawless/no-floating-point-equality",
 	"flawless/no-redundant-tsconfig-options",
+	"flawless/no-shared-mocks",
 	"flawless/no-unnecessary-use-callback",
 	"flawless/no-unnecessary-use-memo",
 	"flawless/padding-after-expect-assertions",