Files
clean-architecture-frontend…/src/contracts/product-features.ts
T
DongHyeonkaandClaude Opus 5.5 b685b616e4 fix(bootstrap): report FEATURE_OVERRIDES keys the build does not declare (09-09)
A misspelt kill-switch key was ignored without a trace, so the feature kept
running. Boot now records feature.override.unknown once per such key, and
release admission lists them as warnings in its record without refusing the
artifact (a shared document may still name another build's features).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 23:25:24 +09:00

162 lines
5.9 KiB
TypeScript

/**
* §3.5 / §6.1. Which product features this build contains, and which of them a
* deployment is allowed to switch off.
*
* Two different questions, deliberately answered by two different inputs:
*
* - **Installed** is a build-time decision. `VITE_PRODUCT_FEATURES` selects
* from the features this source tree declares. The index generator
* (`scripts/generate-product-feature-index.ts`) applies it before anything is
* compiled (09-02, D-9), so a feature left out is not imported by the bundle,
* the Node build scripts or the context router, and a misspelt id fails the
* first build step. Deleting the feature directory is still the way to take
* its source out of the repository; FE-GATE-020 proves that works.
* - **Active** is a runtime decision. `FEATURE_OVERRIDES` in the runtime config
* may take an installed feature out of service without a rebuild.
*
* Both directions are subtractive, and that is the invariant this module
* exists to hold: neither input can ever turn on a feature whose source is
* absent. A configuration document that could name a feature into existence
* would be a configuration document that chooses which code runs, and no
* dynamic import path is ever built from one.
*/
export type ProductFeatureOverride = "DEFAULT" | "DISABLED";
export type ProductFeatureState =
/** Compiled in and not disabled: the feature serves traffic. */
| "ACTIVE"
/** Compiled in, switched off by the runtime document. */
| "DISABLED_BY_CONFIG"
/** Not selected at build time; not in the bundle. */
| "NOT_INSTALLED";
export type ProductFeatureOverrideMap = Readonly<
Record<string, ProductFeatureOverride>
>;
export type ProductFeatureStatus = Readonly<{
featureId: string;
state: ProductFeatureState;
}>;
/** The shape every feature contract exposes to the manifest. */
export type SelectableProductFeature = Readonly<{ featureId: string }>;
/**
* The explicit "no product features" selection.
*
* A blank value cannot mean it: an unset CI variable expands to a blank string
* far too easily, and a build that silently shipped no features would be a very
* expensive way to learn that. Selecting nothing has to be something you typed.
*/
export const NO_PRODUCT_FEATURES = "none";
/**
* Applies the build-time selection to the features this source tree declares.
*
* An empty or absent declaration keeps everything, so an ordinary build needs
* no environment at all. A declaration naming something that is not compiled is
* refused rather than ignored: silently accepting it would let a deployment
* believe it had enabled a feature that does not exist.
*/
export function selectCompiledProductFeatures<
Feature extends SelectableProductFeature,
>(
compiled: readonly Feature[],
declared: string | undefined,
): readonly Feature[] {
const compiledIds = compiled.map((feature) => feature.featureId);
assertUniqueFeatureIds(compiledIds);
const compiledIdSet = new Set(compiledIds);
if (declared === undefined || declared.trim() === "") {
return Object.freeze([...compiled]);
}
if (declared.trim() === NO_PRODUCT_FEATURES) return Object.freeze([]);
const requested = declared
.split(",")
.map((entry) => entry.trim())
.filter((entry) => entry.length > 0);
if (requested.length === 0) {
throw new Error(
`VITE_PRODUCT_FEATURES is set to ${JSON.stringify(declared)}, which names ` +
`no feature. Use "${NO_PRODUCT_FEATURES}" to select none, or leave it ` +
`unset to keep ${compiledIds.join(", ")}.`,
);
}
const unknown = requested.filter((id) => !compiledIdSet.has(id));
if (unknown.length > 0) {
throw new Error(
`VITE_PRODUCT_FEATURES names features this build does not contain: ${unknown.join(
", ",
)}. Selection can only remove from ${compiledIds.join(", ")}.`,
);
}
const requestedSet = new Set(requested);
return Object.freeze(
compiled.filter((feature) => requestedSet.has(feature.featureId)),
);
}
/**
* The state of every feature the source tree declares, given what was compiled
* and what the runtime document says.
*
* `compiledIds` is the full declared set rather than the installed one so a
* build that dropped a feature still reports it as `NOT_INSTALLED` instead of
* omitting it. An operator looking at the platform overview needs to see the
* difference between "off" and "never heard of it".
*/
export function resolveProductFeatures(
compiledIds: readonly string[],
installedIds: readonly string[],
overrides: ProductFeatureOverrideMap = {},
): readonly ProductFeatureStatus[] {
assertUniqueFeatureIds(compiledIds);
const installedIdSet = new Set(installedIds);
return Object.freeze(
[...compiledIds].sort().map((featureId) =>
Object.freeze({
featureId,
state: !installedIdSet.has(featureId)
? ("NOT_INSTALLED" as const)
: overrides[featureId] === "DISABLED"
? ("DISABLED_BY_CONFIG" as const)
: ("ACTIVE" as const),
}),
),
);
}
/**
* 09-09. Override keys naming no feature this build declares. They stay inert,
* since one runtime document may serve builds with different features, but a
* misspelt kill switch has to be reported rather than silently ignored.
*/
export function unknownProductFeatureOverrides(
compiledIds: readonly string[],
overrides: ProductFeatureOverrideMap = {},
): readonly string[] {
const declared = new Set(compiledIds);
return Object.freeze(
Object.keys(overrides).filter((featureId) => !declared.has(featureId)).sort(),
);
}
/** The feature ids serving traffic right now. */
export function activeProductFeatureIds(
statuses: readonly ProductFeatureStatus[],
): readonly string[] {
return Object.freeze(
statuses
.filter((status) => status.state === "ACTIVE")
.map((status) => status.featureId),
);
}
function assertUniqueFeatureIds(ids: readonly string[]): void {
if (new Set(ids).size !== ids.length) {
throw new Error(`duplicate product feature id: ${ids.join(", ")}`);
}
}