refactor: consolidate coercion contracts (#122458)

* refactor: consolidate coercion contracts

Centralize exact string, record, numeric, date, Boolean, argument, and structured-error coercions while preserving call-site semantics.

Migrate canonical-name collisions and deprecated internal SDK bypasses, deleting 55 net production/tooling lines. Expand declaration ownership enforcement to 101 allowed helpers and add a narrow export-completeness audit.

* fix: preserve standalone script coercions

Keep copied Control UI tooling self-contained and retain the trusted release harness module-relative source seam when the harness runs against an old target cwd.
This commit is contained in:
Peter Steinberger
2026-08-11 23:26:37 -07:00
committed by GitHub
parent 66fe424590
commit b080dd1e76
276 changed files with 1685 additions and 1663 deletions
+54
View File
@@ -47,6 +47,9 @@
* onUnhandledArg?: (arg: string, args: T) => "handled" | void,
* }} ParseOptions
*/
/**
* @typedef {{ kind: "syntax" } | { kind: "below" } | { kind: "above" } | { kind: "value", value: number }} BoundedUnsignedDecimalResult
*/
/** @param {string} message */
function failFlagParse(message) {
throw new Error(message);
@@ -170,6 +173,57 @@ function readFlagOptionValue(argv, index, flag) {
}
return { nextIndex: index + 1, value };
}
/**
* Parse the exact lowercase Boolean language used by strict script arguments.
* @param {unknown} value
* @param {string} label
*/
export function parseStrictBooleanArg(value, label) {
if (value === "true") {
return true;
}
if (value === "false") {
return false;
}
throw new Error(`${label} must be true or false.`);
}
/**
* Classify an ASCII unsigned-decimal token against inclusive bounds.
* @param {unknown} value
* @param {number} min
* @param {number} max
* @returns {BoundedUnsignedDecimalResult}
*/
export function classifyBoundedUnsignedDecimal(value, min, max) {
if (typeof value !== "string" || !/^\d+$/u.test(value)) {
return { kind: "syntax" };
}
const parsed = Number(value);
if (parsed < min) {
return { kind: "below" };
}
if (parsed > max) {
return { kind: "above" };
}
return { kind: "value", value: parsed };
}
const PERMISSIVE_BOOLEAN_TRUE_TOKENS = new Set(["1", "on", "true", "yes"]);
const PERMISSIVE_BOOLEAN_FALSE_TOKENS = new Set(["0", "false", "no", "off"]);
/**
* Parse the normalized Boolean token language shared by repository scripts.
* @param {unknown} value
* @returns {boolean | undefined}
*/
export function parsePermissiveBooleanToken(value) {
const normalized = typeof value === "string" ? value.trim().toLowerCase() : "";
if (!normalized) {
return undefined;
}
if (PERMISSIVE_BOOLEAN_TRUE_TOKENS.has(normalized)) {
return true;
}
return PERMISSIVE_BOOLEAN_FALSE_TOKENS.has(normalized) ? false : undefined;
}
/**
* @param {string} raw
* @param {string} flag