@yedoma-labs/kulyn-flags 0.0.0-stage → 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,125 @@
+/**
+ * Why a flag exists. Each kind has its own default maximum lifetime.
+ */
+type FlagKind = "release" | "experiment" | "ops" | "permission";
+/**
+ * A single entry in the flag register.
+ *
+ * Dates are ISO 8601 strings. `createdAt` and `expiresAt` accept `YYYY-MM-DD` or a
+ * date-time with an explicit timezone (`Z` or `+HH:MM`).
+ */
+interface FlagDefinition {
+  /** Flag key, e.g. `checkout.new-ui`. Must match `/^[a-z][a-z0-9-.]{1,79}$/`. */
+  key: string;
+  /** Team or person responsible for removing the flag. Must not be blank. */
+  owner: string;
+  kind: FlagKind;
+  createdAt: string;
+  /** Date after which the flag is considered expired. */
+  expiresAt?: string;
+  description?: string;
+}
+/**
+ * Per-kind maximum lifetime in days. `null` disables the limit for that kind.
+ */
+type MaxLifetimeDays = Readonly<Record<FlagKind, number | null>>;
+/**
+ * Overrides for the default maximum lifetimes. Keys that are omitted keep their default.
+ */
+type LifetimeOverrides = Partial<Record<FlagKind, number | null>>;
+interface DefineFlagsOptions {
+  maxLifetimeDays?: LifetimeOverrides;
+}
+type HygieneCode = "EXPIRED" | "EXCEEDS_MAX_LIFETIME" | "UNUSED" | "UNREGISTERED_USAGE";
+interface HygieneFinding {
+  key: string;
+  code: HygieneCode;
+  message: string;
+}
+interface CheckFlagHygieneOptions {
+  flags: readonly FlagDefinition[];
+  /** Reference time for expiry checks. Defaults to the current time. */
+  now?: Date;
+  /**
+   * Flag keys found in the code base. When omitted, no usage findings are produced.
+   */
+  usedKeys?: Iterable<string>;
+  /** Maximum lifetimes used for `EXCEEDS_MAX_LIFETIME`. Defaults match `defineFlags`. */
+  maxLifetimeDays?: LifetimeOverrides;
+}
+interface AssertFlagHygieneOptions {
+  /** Finding codes that cause a throw. Defaults to all codes. */
+  failOn?: readonly HygieneCode[];
+}
+interface FindFlagKeysOptions {
+  /**
+   * Function names whose first string argument is a flag key.
+   * Defaults to `isEnabled`, `getFlag`, `flag` and `evaluate`.
+   */
+  functions?: readonly string[];
+}
+type FlagRegistryErrorCode = "INVALID_DEFINITION" | "INVALID_KEY" | "DUPLICATE_KEY" | "EMPTY_OWNER" | "INVALID_KIND" | "INVALID_DESCRIPTION" | "INVALID_DATE" | "EXPIRY_NOT_AFTER_CREATION" | "MISSING_EXPIRY" | "EXCEEDS_MAX_LIFETIME" | "INVALID_OPTIONS";
+/**
+ * Thrown when a flag register or its options are invalid.
+ */
+export declare class FlagRegistryError extends Error {
+  readonly code: FlagRegistryErrorCode;
+  /** The offending flag key, when it is known. */
+  readonly key: string | undefined;
+  constructor(code: FlagRegistryErrorCode, message: string, key?: string);
+}
+/**
+ * Thrown by `assertFlagHygiene` when findings match the `failOn` codes.
+ */
+export declare class FlagHygieneError extends Error {
+  readonly code: HygieneCode;
+  readonly findings: readonly HygieneFinding[];
+  constructor(findings: readonly HygieneFinding[]);
+}
+/**
+ * Checks a flag register for flags that should be cleaned up.
+ *
+ * - `EXPIRED`: `now` is at or after `expiresAt`.
+ * - `EXCEEDS_MAX_LIFETIME`: the flag lives longer than the configured maximum for its kind.
+ *   This catches flags registered before a limit was lowered.
+ * - `UNUSED`: only when `usedKeys` is given. The key is registered but not used.
+ * - `UNREGISTERED_USAGE`: only when `usedKeys` is given. The key is used but not registered.
+ *
+ * Findings are sorted by key, then by code.
+ */
+export declare function checkFlagHygiene(options: CheckFlagHygieneOptions): readonly HygieneFinding[];
+/**
+ * Throws `FlagHygieneError` if any finding has a code listed in `failOn`.
+ * Defaults to all codes. Use it in tests or CI.
+ */
+export declare function assertFlagHygiene(findings: readonly HygieneFinding[], options?: AssertFlagHygieneOptions): void;
+/**
+ * Default maximum lifetimes. `permission` flags may live without limit.
+ */
+export declare const DEFAULT_MAX_LIFETIME_DAYS: MaxLifetimeDays;
+/**
+ * Validates a flag register and returns a frozen, normalized copy.
+ *
+ * Throws `FlagRegistryError` with a `code` for the first invalid entry.
+ * A flag kind with a finite maximum lifetime requires `expiresAt`, so that a flag
+ * cannot escape the limit by omitting the date.
+ */
+export declare function defineFlags(definitions: readonly FlagDefinition[], options?: DefineFlagsOptions): readonly FlagDefinition[];
+/**
+ * Finds flag keys in source text.
+ *
+ * Recognized forms, with single or double quotes:
+ * - `isEnabled("key")`, `getFlag('key')` and the other configured function names
+ * - `flags.key` (identifier-style keys only)
+ * - `flags["key"]`
+ *
+ * Text in comments, and template literals (backticks), are ignored, including `${...}`
+ * placeholders in template literals that are not code. Calls inside `${...}` are still scanned.
+ * This function does not read files. The caller passes the text.
+ *
+ * Limitations: regex literals containing quotes are not understood. A quote inside a
+ * regex literal can hide code on the same line.
+ */
+export declare function findFlagKeysInSource(sourceText: string, options?: FindFlagKeysOptions): Set<string>;
+export type { AssertFlagHygieneOptions, CheckFlagHygieneOptions, DefineFlagsOptions, FindFlagKeysOptions, FlagDefinition, FlagKind, FlagRegistryErrorCode, HygieneCode, HygieneFinding, LifetimeOverrides, MaxLifetimeDays };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Why a flag exists. Each kind has its own default maximum lifetime.
+ */
+type FlagKind = "release" | "experiment" | "ops" | "permission";
+/**
+ * A single entry in the flag register.
+ *
+ * Dates are ISO 8601 strings. `createdAt` and `expiresAt` accept `YYYY-MM-DD` or a
+ * date-time with an explicit timezone (`Z` or `+HH:MM`).
+ */
+interface FlagDefinition {
+  /** Flag key, e.g. `checkout.new-ui`. Must match `/^[a-z][a-z0-9-.]{1,79}$/`. */
+  key: string;
+  /** Team or person responsible for removing the flag. Must not be blank. */
+  owner: string;
+  kind: FlagKind;
+  createdAt: string;
+  /** Date after which the flag is considered expired. */
+  expiresAt?: string;
+  description?: string;
+}
+/**
+ * Per-kind maximum lifetime in days. `null` disables the limit for that kind.
+ */
+type MaxLifetimeDays = Readonly<Record<FlagKind, number | null>>;
+/**
+ * Overrides for the default maximum lifetimes. Keys that are omitted keep their default.
+ */
+type LifetimeOverrides = Partial<Record<FlagKind, number | null>>;
+interface DefineFlagsOptions {
+  maxLifetimeDays?: LifetimeOverrides;
+}
+type HygieneCode = "EXPIRED" | "EXCEEDS_MAX_LIFETIME" | "UNUSED" | "UNREGISTERED_USAGE";
+interface HygieneFinding {
+  key: string;
+  code: HygieneCode;
+  message: string;
+}
+interface CheckFlagHygieneOptions {
+  flags: readonly FlagDefinition[];
+  /** Reference time for expiry checks. Defaults to the current time. */
+  now?: Date;
+  /**
+   * Flag keys found in the code base. When omitted, no usage findings are produced.
+   */
+  usedKeys?: Iterable<string>;
+  /** Maximum lifetimes used for `EXCEEDS_MAX_LIFETIME`. Defaults match `defineFlags`. */
+  maxLifetimeDays?: LifetimeOverrides;
+}
+interface AssertFlagHygieneOptions {
+  /** Finding codes that cause a throw. Defaults to all codes. */
+  failOn?: readonly HygieneCode[];
+}
+interface FindFlagKeysOptions {
+  /**
+   * Function names whose first string argument is a flag key.
+   * Defaults to `isEnabled`, `getFlag`, `flag` and `evaluate`.
+   */
+  functions?: readonly string[];
+}
+type FlagRegistryErrorCode = "INVALID_DEFINITION" | "INVALID_KEY" | "DUPLICATE_KEY" | "EMPTY_OWNER" | "INVALID_KIND" | "INVALID_DESCRIPTION" | "INVALID_DATE" | "EXPIRY_NOT_AFTER_CREATION" | "MISSING_EXPIRY" | "EXCEEDS_MAX_LIFETIME" | "INVALID_OPTIONS";
+/**
+ * Thrown when a flag register or its options are invalid.
+ */
+export declare class FlagRegistryError extends Error {
+  readonly code: FlagRegistryErrorCode;
+  /** The offending flag key, when it is known. */
+  readonly key: string | undefined;
+  constructor(code: FlagRegistryErrorCode, message: string, key?: string);
+}
+/**
+ * Thrown by `assertFlagHygiene` when findings match the `failOn` codes.
+ */
+export declare class FlagHygieneError extends Error {
+  readonly code: HygieneCode;
+  readonly findings: readonly HygieneFinding[];
+  constructor(findings: readonly HygieneFinding[]);
+}
+/**
+ * Checks a flag register for flags that should be cleaned up.
+ *
+ * - `EXPIRED`: `now` is at or after `expiresAt`.
+ * - `EXCEEDS_MAX_LIFETIME`: the flag lives longer than the configured maximum for its kind.
+ *   This catches flags registered before a limit was lowered.
+ * - `UNUSED`: only when `usedKeys` is given. The key is registered but not used.
+ * - `UNREGISTERED_USAGE`: only when `usedKeys` is given. The key is used but not registered.
+ *
+ * Findings are sorted by key, then by code.
+ */
+export declare function checkFlagHygiene(options: CheckFlagHygieneOptions): readonly HygieneFinding[];
+/**
+ * Throws `FlagHygieneError` if any finding has a code listed in `failOn`.
+ * Defaults to all codes. Use it in tests or CI.
+ */
+export declare function assertFlagHygiene(findings: readonly HygieneFinding[], options?: AssertFlagHygieneOptions): void;
+/**
+ * Default maximum lifetimes. `permission` flags may live without limit.
+ */
+export declare const DEFAULT_MAX_LIFETIME_DAYS: MaxLifetimeDays;
+/**
+ * Validates a flag register and returns a frozen, normalized copy.
+ *
+ * Throws `FlagRegistryError` with a `code` for the first invalid entry.
+ * A flag kind with a finite maximum lifetime requires `expiresAt`, so that a flag
+ * cannot escape the limit by omitting the date.
+ */
+export declare function defineFlags(definitions: readonly FlagDefinition[], options?: DefineFlagsOptions): readonly FlagDefinition[];
+/**
+ * Finds flag keys in source text.
+ *
+ * Recognized forms, with single or double quotes:
+ * - `isEnabled("key")`, `getFlag('key')` and the other configured function names
+ * - `flags.key` (identifier-style keys only)
+ * - `flags["key"]`
+ *
+ * Text in comments, and template literals (backticks), are ignored, including `${...}`
+ * placeholders in template literals that are not code. Calls inside `${...}` are still scanned.
+ * This function does not read files. The caller passes the text.
+ *
+ * Limitations: regex literals containing quotes are not understood. A quote inside a
+ * regex literal can hide code on the same line.
+ */
+export declare function findFlagKeysInSource(sourceText: string, options?: FindFlagKeysOptions): Set<string>;
+export type { AssertFlagHygieneOptions, CheckFlagHygieneOptions, DefineFlagsOptions, FindFlagKeysOptions, FlagDefinition, FlagKind, FlagRegistryErrorCode, HygieneCode, HygieneFinding, LifetimeOverrides, MaxLifetimeDays };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,388 @@
+// src/errors.ts
+/**
+* Thrown when a flag register or its options are invalid.
+*/
+var FlagRegistryError = class extends Error {
+	code;
+	/** The offending flag key, when it is known. */
+	key;
+	constructor(code, message, key) {
+		super(message);
+		this.name = "FlagRegistryError";
+		this.code = code;
+		this.key = key;
+	}
+};
+/**
+* Thrown by `assertFlagHygiene` when findings match the `failOn` codes.
+*/
+var FlagHygieneError = class extends Error {
+	code;
+	findings;
+	constructor(findings) {
+		const lines = findings.map((finding) => `  - [${finding.code}] ${finding.message}`);
+		super(`Flag hygiene check failed with ${findings.length} finding(s):\n${lines.join("\n")}`);
+		this.name = "FlagHygieneError";
+		this.code = findings[0]?.code ?? "UNUSED";
+		this.findings = findings;
+	}
+};
+// src/dates.ts
+const DAY_MS = 864e5;
+/**
+* `YYYY-MM-DD`, optionally followed by `T HH:MM[:SS[.fraction]]` and a mandatory timezone.
+* Only fixed quantifiers and a single optional group, so matching is linear.
+*/
+const ISO_PATTERN = /^(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,9}))?)?(Z|[+-]\d{2}:\d{2}))?$/;
+function isLeapYear(year) {
+	return year % 4 === 0 && year % 100 !== 0 || year % 400 === 0;
+}
+function daysInMonth(year, month) {
+	return [
+		31,
+		isLeapYear(year) ? 29 : 28,
+		31,
+		30,
+		31,
+		30,
+		31,
+		31,
+		30,
+		31,
+		30,
+		31
+	][month - 1] ?? 0;
+}
+/**
+* Parses a strict ISO 8601 date or date-time and returns epoch milliseconds.
+* Returns `undefined` for anything that is not a real calendar date and time.
+*/
+function parseIsoDate(value) {
+	if (typeof value !== "string") return;
+	const match = ISO_PATTERN.exec(value);
+	if (match === null) return;
+	const year = Number(match[1]);
+	const month = Number(match[2]);
+	const day = Number(match[3]);
+	if (month < 1 || month > 12 || day < 1 || day > daysInMonth(year, month)) return;
+	if (match[4] !== void 0) {
+		const hours = Number(match[4]);
+		const minutes = Number(match[5]);
+		const seconds = match[6] === void 0 ? 0 : Number(match[6]);
+		if (hours > 23 || minutes > 59 || seconds > 59) return;
+		const offset = match[8];
+		if (offset !== void 0 && offset !== "Z") {
+			const offsetHours = Number(offset.slice(1, 3));
+			const offsetMinutes = Number(offset.slice(4, 6));
+			if (offsetHours > 23 || offsetMinutes > 59) return;
+		}
+	}
+	const time = Date.parse(value);
+	return Number.isNaN(time) ? void 0 : time;
+}
+// src/lifetimes.ts
+const FLAG_KINDS = [
+	"release",
+	"experiment",
+	"ops",
+	"permission"
+];
+/**
+* Default maximum lifetimes. `permission` flags may live without limit.
+*/
+const DEFAULT_MAX_LIFETIME_DAYS = Object.freeze({
+	release: 90,
+	experiment: 30,
+	ops: 365,
+	permission: null
+});
+function isFlagKind(value) {
+	return typeof value === "string" && FLAG_KINDS.includes(value);
+}
+/**
+* Merges user overrides into the defaults and validates them.
+*/
+function resolveMaxLifetimeDays(overrides) {
+	const resolved = { ...DEFAULT_MAX_LIFETIME_DAYS };
+	if (overrides === void 0) return resolved;
+	if (typeof overrides !== "object" || overrides === null) throw new FlagRegistryError("INVALID_OPTIONS", "maxLifetimeDays must be an object");
+	for (const kind of Object.keys(overrides)) {
+		if (!isFlagKind(kind)) throw new FlagRegistryError("INVALID_OPTIONS", `Unknown flag kind in maxLifetimeDays: "${kind}"`);
+		const value = overrides[kind];
+		if (value === void 0) continue;
+		if (value !== null && !(Number.isInteger(value) && value > 0)) throw new FlagRegistryError("INVALID_OPTIONS", `maxLifetimeDays.${kind} must be a positive integer or null, got ${String(value)}`);
+		resolved[kind] = value;
+	}
+	return resolved;
+}
+// src/hygiene.ts
+/** Order of codes in the result when two findings share a key. */
+const CODE_ORDER = [
+	"EXPIRED",
+	"EXCEEDS_MAX_LIFETIME",
+	"UNUSED",
+	"UNREGISTERED_USAGE"
+];
+/**
+* Checks a flag register for flags that should be cleaned up.
+*
+* - `EXPIRED`: `now` is at or after `expiresAt`.
+* - `EXCEEDS_MAX_LIFETIME`: the flag lives longer than the configured maximum for its kind.
+*   This catches flags registered before a limit was lowered.
+* - `UNUSED`: only when `usedKeys` is given. The key is registered but not used.
+* - `UNREGISTERED_USAGE`: only when `usedKeys` is given. The key is used but not registered.
+*
+* Findings are sorted by key, then by code.
+*/
+function checkFlagHygiene(options) {
+	const nowMs = resolveNow(options.now);
+	const lifetimes = resolveMaxLifetimeDays(options.maxLifetimeDays);
+	const registered = /* @__PURE__ */ new Set();
+	const findings = [];
+	for (const flag of options.flags) {
+		if (registered.has(flag.key)) throw new FlagRegistryError("DUPLICATE_KEY", `Duplicate flag key "${flag.key}"`, flag.key);
+		registered.add(flag.key);
+		collectLifecycleFindings(flag, nowMs, lifetimes[flag.kind], findings);
+	}
+	if (options.usedKeys !== void 0) {
+		const used = new Set(options.usedKeys);
+		for (const key of registered) if (!used.has(key)) findings.push({
+			key,
+			code: "UNUSED",
+			message: `Flag "${key}" is registered but not used`
+		});
+		for (const key of used) if (!registered.has(key)) findings.push({
+			key,
+			code: "UNREGISTERED_USAGE",
+			message: `Flag "${key}" is used but not registered`
+		});
+	}
+	return findings.sort((a, b) => compareStrings(a.key, b.key) || CODE_ORDER.indexOf(a.code) - CODE_ORDER.indexOf(b.code));
+}
+/**
+* Throws `FlagHygieneError` if any finding has a code listed in `failOn`.
+* Defaults to all codes. Use it in tests or CI.
+*/
+function assertFlagHygiene(findings, options) {
+	const failOn = new Set(options?.failOn ?? CODE_ORDER);
+	const failing = findings.filter((finding) => failOn.has(finding.code));
+	if (failing.length > 0) throw new FlagHygieneError(failing);
+}
+function collectLifecycleFindings(flag, nowMs, maxDays, findings) {
+	if (!isFlagKind(flag.kind)) throw new FlagRegistryError("INVALID_KIND", `Flag "${flag.key}" has invalid kind`, flag.key);
+	const createdMs = parseIsoDate(flag.createdAt);
+	if (createdMs === void 0) throw new FlagRegistryError("INVALID_DATE", `Flag "${flag.key}" has invalid createdAt`, flag.key);
+	if (flag.expiresAt === void 0) return;
+	const expiresMs = parseIsoDate(flag.expiresAt);
+	if (expiresMs === void 0) throw new FlagRegistryError("INVALID_DATE", `Flag "${flag.key}" has invalid expiresAt`, flag.key);
+	if (nowMs >= expiresMs) findings.push({
+		key: flag.key,
+		code: "EXPIRED",
+		message: `Flag "${flag.key}" expired at ${flag.expiresAt}`
+	});
+	if (maxDays !== null && maxDays !== void 0) {
+		const lifetimeMs = expiresMs - createdMs;
+		if (lifetimeMs > maxDays * 864e5) findings.push({
+			key: flag.key,
+			code: "EXCEEDS_MAX_LIFETIME",
+			message: `Flag "${flag.key}" (${flag.kind}) lives ${lifetimeMs / DAY_MS} days, the maximum is ${maxDays}`
+		});
+	}
+}
+function resolveNow(now) {
+	if (now === void 0) return Date.now();
+	const time = now.getTime();
+	if (Number.isNaN(time)) throw new FlagRegistryError("INVALID_OPTIONS", "now is an invalid Date");
+	return time;
+}
+function compareStrings(a, b) {
+	if (a === b) return 0;
+	return a < b ? -1 : 1;
+}
+// src/registry.ts
+const KEY_PATTERN = /^[a-z][a-z0-9-.]{1,79}$/;
+/**
+* Validates a flag register and returns a frozen, normalized copy.
+*
+* Throws `FlagRegistryError` with a `code` for the first invalid entry.
+* A flag kind with a finite maximum lifetime requires `expiresAt`, so that a flag
+* cannot escape the limit by omitting the date.
+*/
+function defineFlags(definitions, options) {
+	if (!Array.isArray(definitions)) throw new FlagRegistryError("INVALID_DEFINITION", "defineFlags expects an array of flags");
+	const maxLifetimeDays = resolveMaxLifetimeDays(options?.maxLifetimeDays);
+	const seen = /* @__PURE__ */ new Set();
+	const result = [];
+	for (const [index, raw] of definitions.entries()) {
+		const flag = validateDefinition(raw, index, maxLifetimeDays);
+		if (seen.has(flag.key)) throw new FlagRegistryError("DUPLICATE_KEY", `Duplicate flag key "${flag.key}"`, flag.key);
+		seen.add(flag.key);
+		result.push(flag);
+	}
+	return Object.freeze(result);
+}
+function validateDefinition(raw, index, maxLifetimeDays) {
+	if (typeof raw !== "object" || raw === null) throw new FlagRegistryError("INVALID_DEFINITION", `Flag at index ${index} is not an object`);
+	const record = raw;
+	const key = record.key;
+	if (typeof key !== "string" || !KEY_PATTERN.test(key)) throw new FlagRegistryError("INVALID_KEY", `Invalid flag key at index ${index}: ${JSON.stringify(key)} (must match ${KEY_PATTERN.source})`, typeof key === "string" ? key : void 0);
+	const owner = record.owner;
+	if (typeof owner !== "string" || owner.trim() === "") throw new FlagRegistryError("EMPTY_OWNER", `Flag "${key}" has no owner`, key);
+	const kind = record.kind;
+	if (!isFlagKind(kind)) throw new FlagRegistryError("INVALID_KIND", `Flag "${key}" has invalid kind ${JSON.stringify(kind)}`, key);
+	const createdAt = record.createdAt;
+	const createdMs = parseIsoDate(createdAt);
+	if (createdMs === void 0) throw new FlagRegistryError("INVALID_DATE", `Flag "${key}" has invalid createdAt ${JSON.stringify(createdAt)}`, key);
+	const expiresAt = record.expiresAt;
+	let expiresMs;
+	if (expiresAt !== void 0) {
+		expiresMs = parseIsoDate(expiresAt);
+		if (expiresMs === void 0) throw new FlagRegistryError("INVALID_DATE", `Flag "${key}" has invalid expiresAt ${JSON.stringify(expiresAt)}`, key);
+		if (expiresMs <= createdMs) throw new FlagRegistryError("EXPIRY_NOT_AFTER_CREATION", `Flag "${key}" expires at ${String(expiresAt)}, which is not after createdAt`, key);
+	}
+	const maxDays = maxLifetimeDays[kind];
+	if (maxDays !== null) {
+		if (expiresMs === void 0) throw new FlagRegistryError("MISSING_EXPIRY", `Flag "${key}" (${kind}) needs an expiresAt, the maximum lifetime is ${maxDays} days`, key);
+		if (expiresMs - createdMs > maxDays * 864e5) throw new FlagRegistryError("EXCEEDS_MAX_LIFETIME", `Flag "${key}" (${kind}) lives longer than the maximum of ${maxDays} days`, key);
+	}
+	const description = record.description;
+	if (description !== void 0 && typeof description !== "string") throw new FlagRegistryError("INVALID_DESCRIPTION", `Flag "${key}" has a non-string description`, key);
+	const flag = {
+		key,
+		owner,
+		kind,
+		createdAt
+	};
+	if (expiresAt !== void 0) flag.expiresAt = expiresAt;
+	if (description !== void 0) flag.description = description;
+	return flag;
+}
+// src/scan.ts
+const DEFAULT_FUNCTIONS = [
+	"isEnabled",
+	"getFlag",
+	"flag",
+	"evaluate"
+];
+/** Upper bound for a key literal. Longer literals are ignored. */
+const MAX_LITERAL_LENGTH = 100;
+/**
+* Finds flag keys in source text.
+*
+* Recognized forms, with single or double quotes:
+* - `isEnabled("key")`, `getFlag('key')` and the other configured function names
+* - `flags.key` (identifier-style keys only)
+* - `flags["key"]`
+*
+* Text in comments, and template literals (backticks), are ignored, including `${...}`
+* placeholders in template literals that are not code. Calls inside `${...}` are still scanned.
+* This function does not read files. The caller passes the text.
+*
+* Limitations: regex literals containing quotes are not understood. A quote inside a
+* regex literal can hide code on the same line.
+*/
+function findFlagKeysInSource(sourceText, options) {
+	const functions = options?.functions ?? DEFAULT_FUNCTIONS;
+	const code = maskNonCode(sourceText);
+	const keys = /* @__PURE__ */ new Set();
+	if (functions.length > 0) {
+		const alternation = functions.map(escapeRegExp).join("|");
+		const callPattern = new RegExp(String.raw`\b(?:${alternation})\s*\(\s*(["'])([^"'\\\r\n]{1,${MAX_LITERAL_LENGTH}})\1(?=\s*[,)])`, "g");
+		for (const match of code.matchAll(callPattern)) {
+			const key = match[2];
+			if (key !== void 0) keys.add(key);
+		}
+	}
+	for (const match of code.matchAll(/\bflags\.([a-z][a-z0-9]*)(?![\w.-]|\s*\()/g)) {
+		const key = match[1];
+		if (key !== void 0) keys.add(key);
+	}
+	const bracketPattern = new RegExp(String.raw`\bflags\s*\[\s*(["'])([^"'\\\r\n]{1,${MAX_LITERAL_LENGTH}})\1\s*\]`, "g");
+	for (const match of code.matchAll(bracketPattern)) {
+		const key = match[2];
+		if (key !== void 0) keys.add(key);
+	}
+	return keys;
+}
+/**
+* Returns `source` with comments and template-literal text replaced by spaces.
+* Newlines are kept, so the output has the same length and line structure.
+* Single- and double-quoted strings are kept, because keys are read from them.
+* Runs in linear time: each character is visited a constant number of times.
+*/
+function maskNonCode(source) {
+	const out = source.split("");
+	const n = source.length;
+	const frames = [{
+		kind: "code",
+		braces: 0,
+		interpolation: false
+	}];
+	const mask = (from, to) => {
+		for (let k = from; k < to; k++) if (out[k] !== "\n" && out[k] !== "\r") out[k] = " ";
+	};
+	let i = 0;
+	while (i < n) {
+		const top = frames[frames.length - 1];
+		if (top === void 0) break;
+		const ch = source[i];
+		const next = source[i + 1];
+		if (top.kind === "template") {
+			if (ch === "\\") {
+				mask(i, i + 2);
+				i += 2;
+			} else if (ch === "`") {
+				mask(i, i + 1);
+				frames.pop();
+				i++;
+			} else if (ch === "$" && next === "{") {
+				mask(i, i + 2);
+				frames.push({
+					kind: "code",
+					braces: 0,
+					interpolation: true
+				});
+				i += 2;
+			} else {
+				mask(i, i + 1);
+				i++;
+			}
+			continue;
+		}
+		if (ch === "/" && next === "/") {
+			const newline = source.indexOf("\n", i);
+			const end = newline === -1 ? n : newline;
+			mask(i, end);
+			i = end;
+		} else if (ch === "/" && next === "*") {
+			const close = source.indexOf("*/", i + 2);
+			const end = close === -1 ? n : close + 2;
+			mask(i, end);
+			i = end;
+		} else if (ch === "\"" || ch === "'") {
+			let j = i + 1;
+			while (j < n && source[j] !== ch && source[j] !== "\n") j += source[j] === "\\" ? 2 : 1;
+			i = source[j] === ch ? j + 1 : j;
+		} else if (ch === "`") {
+			mask(i, i + 1);
+			frames.push({ kind: "template" });
+			i++;
+		} else if (ch === "{") {
+			top.braces++;
+			i++;
+		} else if (ch === "}") {
+			if (top.interpolation && top.braces === 0) {
+				mask(i, i + 1);
+				frames.pop();
+			} else if (top.braces > 0) top.braces--;
+			i++;
+		} else i++;
+	}
+	return out.join("");
+}
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+export { DEFAULT_MAX_LIFETIME_DAYS, FlagHygieneError, FlagRegistryError, assertFlagHygiene, checkFlagHygiene, defineFlags, findFlagKeysInSource };
+
+//# sourceMappingURL=index.js.map