@featurevisor/core 2.14.0 → 2.16.0

package/src/generate-code/typescript.ts

@@ -3,12 +3,19 @@ import * as path from "path";
 
 import type {
   Attribute,
+  ParsedFeature,
   Schema,
   VariableSchema,
   VariableSchemaWithInline,
 } from "@featurevisor/types";
 import { Dependencies } from "../dependencies";
 
+export interface TypeScriptGenerationOptions {
+  tag?: string | string[];
+  react?: boolean;
+  individualFeatures?: boolean;
+}
+
 function convertFeaturevisorTypeToTypeScriptType(featurevisorType: string): string {
   switch (featurevisorType) {
     case "boolean":
@@ -383,6 +390,63 @@ function getRelativePath(from, to) {
   return relativePath;
 }
 
+function getVariationUnionFromFeature(parsedFeature: ParsedFeature): string | null {
+  if (!parsedFeature.variations || parsedFeature.variations.length === 0) {
+    return null;
+  }
+
+  const values = Array.from(
+    new Set(parsedFeature.variations.map((variation) => JSON.stringify(variation.value))),
+  );
+
+  return values.length > 0 ? values.join(" | ") : null;
+}
+
+function getVariableTypeForFeaturesMap(
+  variableSchema: VariableSchema,
+  schemasByKey: Record<string, Schema>,
+  schemaTypeNames?: Record<string, string>,
+): { typeName: string; schemaTypesUsed: string[] } {
+  const schemaTypesUsed: string[] = [];
+  const addSchemaUsed = (name: string) => {
+    if (name && !schemaTypesUsed.includes(name)) {
+      schemaTypesUsed.push(name);
+    }
+  };
+
+  if (
+    schemaTypeNames &&
+    "schema" in variableSchema &&
+    variableSchema.schema &&
+    schemasByKey[variableSchema.schema]
+  ) {
+    const schemaTypeName = schemaTypeNames[variableSchema.schema];
+    addSchemaUsed(schemaTypeName);
+    return { typeName: schemaTypeName, schemaTypesUsed };
+  }
+
+  const effective = getEffectiveVariableSchema(variableSchema, schemasByKey);
+  if (!effective) {
+    return { typeName: "unknown", schemaTypesUsed };
+  }
+
+  if ("type" in effective && effective.type === "json") {
+    return { typeName: "unknown", schemaTypesUsed };
+  }
+
+  const typeName = schemaToTypeScriptType(effective as Schema, schemasByKey, schemaTypeNames);
+
+  if (schemaTypeNames) {
+    Object.values(schemaTypeNames).forEach((name) => {
+      if (typeName.includes(name)) {
+        addSchemaUsed(name);
+      }
+    });
+  }
+
+  return { typeName, schemaTypesUsed };
+}
+
 /**
  * Generates the content of Schemas.ts: one exported type per schema key, using schema refs between schemas.
  */
@@ -423,8 +487,19 @@ export function getInstance(): FeaturevisorInstance {
 }
 `.trimStart();
 
-export async function generateTypeScriptCodeForProject(deps: Dependencies, outputPath: string) {
+export async function generateTypeScriptCodeForProject(
+  deps: Dependencies,
+  outputPath: string,
+  options: TypeScriptGenerationOptions = {},
+) {
   const { rootDirectoryPath, datasource } = deps;
+  const selectedTags = options.tag
+    ? Array.isArray(options.tag)
+      ? options.tag
+      : [options.tag]
+    : [];
+  const shouldGenerateReact = Boolean(options.react);
+  const shouldGenerateIndividualFeatures = options.individualFeatures !== false;
 
   console.log("\nGenerating TypeScript code...\n");
 
@@ -474,7 +549,6 @@ ${attributeProperties}
   );
 
   // features
-  const featureNamespaces: string[] = [];
   const featureFiles = await datasource.listFeatures();
 
   // Load schemas for resolving variable schema references
@@ -503,89 +577,109 @@ ${attributeProperties}
     schemaTypeNames[k] = getPascalCase(k) + "Schema";
   }
 
+  const parsedFeatures: {
+    featureKey: string;
+    parsedFeature: ParsedFeature;
+    namespaceValue: string;
+  }[] = [];
+
   for (const featureKey of featureFiles) {
-    const parsedFeature = await datasource.readFeature(featureKey);
+    const parsedFeature = (await datasource.readFeature(featureKey)) as ParsedFeature;
 
     if (typeof parsedFeature.archived !== "undefined" && parsedFeature.archived) {
       continue;
     }
 
-    const namespaceValue = getPascalCase(featureKey) + "Feature";
-    featureNamespaces.push(namespaceValue);
-
-    let variableTypeDeclarations = "";
-    let variableMethods = "";
-    const featureSchemaTypesUsed = new Set<string>();
-
-    if (parsedFeature.variablesSchema) {
-      const variableKeys = Object.keys(parsedFeature.variablesSchema);
-      const allDeclarations: string[] = [];
-
-      for (const variableKey of variableKeys) {
-        const variableSchema = parsedFeature.variablesSchema[variableKey];
-        const effective = getEffectiveVariableSchema(variableSchema, schemasByKey);
-        const variableType = effective?.type;
-        const {
-          declarations,
-          returnTypeName,
-          genericArg,
-          isLiteralType,
-          useGetVariable,
-          schemaTypesUsed,
-        } = generateVariableTypeDeclarations(
-          variableKey,
-          variableSchema,
-          schemasByKey,
-          hasSchemasFile ? schemaTypeNames : undefined,
-        );
-        schemaTypesUsed.forEach((t) => featureSchemaTypesUsed.add(t));
-        allDeclarations.push(...declarations);
+    if (selectedTags.length > 0) {
+      const featureTags = Array.isArray(parsedFeature.tags) ? parsedFeature.tags : [];
+      const hasTags = selectedTags.every((tag) => featureTags.includes(tag));
+      if (!hasTags) {
+        continue;
+      }
+    }
 
-        const internalMethodName = `getVariable${
-          variableType === "json" ? "JSON" : getPascalCase(variableType ?? "string")
-        }`;
+    const namespaceValue = getPascalCase(featureKey) + "Feature";
+    parsedFeatures.push({ featureKey, parsedFeature, namespaceValue });
+  }
 
-        const hasGeneric =
-          variableType === "json" || variableType === "array" || variableType === "object";
-        const literalAssertion = isLiteralType ? ` as ${returnTypeName} | null` : "";
-        if (useGetVariable) {
-          variableMethods += `
+  const featureNamespaces: string[] = [];
+  if (shouldGenerateIndividualFeatures) {
+    for (const { featureKey, parsedFeature, namespaceValue } of parsedFeatures) {
+      featureNamespaces.push(namespaceValue);
+
+      let variableTypeDeclarations = "";
+      let variableMethods = "";
+      const featureSchemaTypesUsed = new Set<string>();
+
+      if (parsedFeature.variablesSchema) {
+        const variableKeys = Object.keys(parsedFeature.variablesSchema);
+        const allDeclarations: string[] = [];
+
+        for (const variableKey of variableKeys) {
+          const variableSchema = parsedFeature.variablesSchema[variableKey];
+          const effective = getEffectiveVariableSchema(variableSchema, schemasByKey);
+          const variableType = effective?.type;
+          const {
+            declarations,
+            returnTypeName,
+            genericArg,
+            isLiteralType,
+            useGetVariable,
+            schemaTypesUsed,
+          } = generateVariableTypeDeclarations(
+            variableKey,
+            variableSchema,
+            schemasByKey,
+            hasSchemasFile ? schemaTypeNames : undefined,
+          );
+          schemaTypesUsed.forEach((t) => featureSchemaTypesUsed.add(t));
+          allDeclarations.push(...declarations);
+
+          const internalMethodName = `getVariable${
+            variableType === "json" ? "JSON" : getPascalCase(variableType ?? "string")
+          }`;
+
+          const hasGeneric =
+            variableType === "json" || variableType === "array" || variableType === "object";
+          const literalAssertion = isLiteralType ? ` as ${returnTypeName} | null` : "";
+          if (useGetVariable) {
+            variableMethods += `
 
 ${INDENT_NS}export function get${getPascalCase(variableKey)}(context: Context = {}): ${returnTypeName} | null {
 ${INDENT_NS_BODY}return getInstance().getVariable(key, "${variableKey}", context)${literalAssertion};
 ${INDENT_NS}}`;
-        } else if (variableType === "json") {
-          variableMethods += `
+          } else if (variableType === "json") {
+            variableMethods += `
 
 ${INDENT_NS}export function get${getPascalCase(variableKey)}<T = unknown>(context: Context = {}): T | null {
 ${INDENT_NS_BODY}return getInstance().${internalMethodName}<T>(key, "${variableKey}", context);
 ${INDENT_NS}}`;
-        } else if (hasGeneric) {
-          variableMethods += `
+          } else if (hasGeneric) {
+            variableMethods += `
 
 ${INDENT_NS}export function get${getPascalCase(variableKey)}(context: Context = {}): ${returnTypeName} | null {
 ${INDENT_NS_BODY}return getInstance().${internalMethodName}<${genericArg}>(key, "${variableKey}", context);
 ${INDENT_NS}}`;
-        } else {
-          variableMethods += `
+          } else {
+            variableMethods += `
 
 ${INDENT_NS}export function get${getPascalCase(variableKey)}(context: Context = {}): ${returnTypeName} | null {
 ${INDENT_NS_BODY}return getInstance().${internalMethodName}(key, "${variableKey}", context)${literalAssertion};
 ${INDENT_NS}}`;
+          }
         }
-      }
 
-      if (allDeclarations.length > 0) {
-        variableTypeDeclarations = "\n\n" + allDeclarations.join("\n\n");
+        if (allDeclarations.length > 0) {
+          variableTypeDeclarations = "\n\n" + allDeclarations.join("\n\n");
+        }
       }
-    }
 
-    const schemasImportLine =
-      featureSchemaTypesUsed.size > 0
-        ? `import type { ${[...featureSchemaTypesUsed].sort().join(", ")} } from "./Schemas";\n\n`
-        : "";
+      const schemasImportLine =
+        featureSchemaTypesUsed.size > 0
+          ? `import type { ${[...featureSchemaTypesUsed].sort().join(", ")} } from "./Schemas";\n\n`
+          : "";
 
-    const featureContent = `
+      const featureContent = `
 import { Context } from "./Context";
 import { getInstance } from "./instance";
 ${schemasImportLine}export namespace ${namespaceValue} {
@@ -601,14 +695,119 @@ ${INDENT_NS}}${variableMethods}
 }
 `.trimStart();
 
-    const featureNamespaceFilePath = path.join(outputPath, `${namespaceValue}.ts`);
-    fs.writeFileSync(featureNamespaceFilePath, featureContent);
-    console.log(
-      `Feature ${featureKey} file written at: ${getRelativePath(
-        rootDirectoryPath,
-        featureNamespaceFilePath,
-      )}`,
-    );
+      const featureNamespaceFilePath = path.join(outputPath, `${namespaceValue}.ts`);
+      fs.writeFileSync(featureNamespaceFilePath, featureContent);
+      console.log(
+        `Feature ${featureKey} file written at: ${getRelativePath(
+          rootDirectoryPath,
+          featureNamespaceFilePath,
+        )}`,
+      );
+    }
+  }
+
+  const featuresTypeSchemasUsed = new Set<string>();
+  const featureTypeEntries = parsedFeatures
+    .map(({ featureKey, parsedFeature }) => {
+      const featureLines: string[] = [];
+      const variationUnion = getVariationUnionFromFeature(parsedFeature);
+
+      if (variationUnion) {
+        featureLines.push(`${INDENT_NS_BODY}variation: ${variationUnion};`);
+      }
+
+      if (parsedFeature.variablesSchema) {
+        for (const [variableKey, variableSchema] of Object.entries(parsedFeature.variablesSchema)) {
+          const { typeName, schemaTypesUsed } = getVariableTypeForFeaturesMap(
+            variableSchema,
+            schemasByKey,
+            hasSchemasFile ? schemaTypeNames : undefined,
+          );
+          schemaTypesUsed.forEach((name) => featuresTypeSchemasUsed.add(name));
+          featureLines.push(`${INDENT_NS_BODY}${JSON.stringify(variableKey)}: ${typeName};`);
+        }
+      }
+
+      return `${INDENT_NS}${JSON.stringify(featureKey)}: {\n${featureLines.join("\n")}\n${INDENT_NS}};`;
+    })
+    .join("\n");
+
+  const featuresSchemasImportLine =
+    featuresTypeSchemasUsed.size > 0
+      ? `import type { ${[...featuresTypeSchemasUsed].sort().join(", ")} } from "./Schemas";\n\n`
+      : "";
+
+  const featuresFileContent = `
+${featuresSchemasImportLine}export type Features = {
+${featureTypeEntries}
+};
+
+export type FeatureKey = keyof Features;
+export type VariableKey<F extends FeatureKey> = Extract<Exclude<keyof Features[F], "variation">, string>;
+export type VariableType<F extends FeatureKey, V extends VariableKey<F>> = Features[F][V];
+export type Variation<F extends FeatureKey> = Features[F] extends { variation: infer V } ? V : never;
+`.trimStart();
+  const featuresFilePath = path.join(outputPath, "Features.ts");
+  fs.writeFileSync(featuresFilePath, featuresFileContent);
+  console.log(`Features file written at: ${getRelativePath(rootDirectoryPath, featuresFilePath)}`);
+
+  const functionsFileContent = `
+import { FeatureKey, Variation, VariableKey, VariableType } from "./Features";
+import { Context } from "./Context";
+import { getInstance } from "./instance";
+
+export function isEnabled(featureKey: FeatureKey, context: Context = {}): boolean {
+  return getInstance().isEnabled(featureKey, context);
+}
+
+export function getVariation<F extends FeatureKey>(featureKey: F, context: Context = {}): Variation<F> | null {
+  return getInstance().getVariation(featureKey, context) as Variation<F> | null;
+}
+
+export function getVariable<F extends FeatureKey, V extends VariableKey<F>>(
+  featureKey: F,
+  variableKey: V,
+  context: Context = {},
+): VariableType<F, V> | null {
+  return getInstance().getVariable(featureKey, variableKey, context) as VariableType<F, V> | null;
+}
+`.trimStart();
+  const functionsFilePath = path.join(outputPath, "Functions.ts");
+  fs.writeFileSync(functionsFilePath, functionsFileContent);
+  console.log(
+    `Functions file written at: ${getRelativePath(rootDirectoryPath, functionsFilePath)}`,
+  );
+
+  if (shouldGenerateReact) {
+    const reactFileContent = `
+import {
+  useFlag as useFlagOriginal,
+  useVariation as useVariationOriginal,
+  useVariable as useVariableOriginal,
+} from "@featurevisor/react";
+
+import { FeatureKey, Variation, VariableKey, VariableType } from "./Features";
+import { Context } from "./Context";
+
+export function useFlag(featureKey: FeatureKey, context: Context = {}): boolean {
+  return useFlagOriginal(featureKey, context);
+}
+
+export function useVariation<F extends FeatureKey>(featureKey: F, context: Context = {}): Variation<F> | null {
+  return useVariationOriginal(featureKey, context) as Variation<F> | null;
+}
+
+export function useVariable<F extends FeatureKey, V extends VariableKey<F>>(
+  featureKey: F,
+  variableKey: V,
+  context: Context = {},
+): VariableType<F, V> | null {
+  return useVariableOriginal(featureKey, variableKey, context) as VariableType<F, V> | null;
+}
+`.trimStart();
+    const reactFilePath = path.join(outputPath, "React.ts");
+    fs.writeFileSync(reactFilePath, reactFileContent);
+    console.log(`React file written at: ${getRelativePath(rootDirectoryPath, reactFilePath)}`);
   }
 
   // index
@@ -617,6 +816,9 @@ ${INDENT_NS}}${variableMethods}
       `export * from "./Context";`,
       `export * from "./instance";`,
       ...(hasSchemasFile ? [`export * from "./Schemas";`] : []),
+      `export * from "./Features";`,
+      `export * from "./Functions";`,
+      ...(shouldGenerateReact ? [`export * from "./React";`] : []),
       ...featureNamespaces.map((featureNamespace) => {
         return `export * from "./${featureNamespace}";`;
       }),

package/src/linter/conditionSchema.spec.ts

@@ -21,7 +21,9 @@ function minimalProjectConfig(): ProjectConfig {
     datafileNamePattern: "",
     revisionFileName: "",
     siteExportDirectoryPath: "",
+    environmentsDirectoryPath: "",
     environments: ["staging", "production"],
+    splitByEnvironment: false,
     tags: ["all"],
     adapter: {},
     plugins: [],

package/src/linter/featureSchema.spec.ts

@@ -25,7 +25,9 @@ function minimalProjectConfig(overrides: Partial<ProjectConfig> = {}): ProjectCo
     datafileNamePattern: "",
     revisionFileName: "",
     siteExportDirectoryPath: "",
+    environmentsDirectoryPath: "",
     environments: ["staging", "production"],
+    splitByEnvironment: false,
     tags: ["all"],
     adapter: {},
     plugins: [],
@@ -678,6 +680,25 @@ describe("featureSchema.ts :: getFeatureZodSchema (variablesSchema and variable
         "not defined in",
       );
     });
+
+    it("rejects rule variable key when feature has no variablesSchema", () => {
+      expectParseFailure(
+        baseFeature({
+          rules: {
+            staging: [{ key: "r1", segments: "*", percentage: 100 }],
+            production: [
+              {
+                key: "r1",
+                segments: "*",
+                percentage: 80,
+                variables: { blah123: "some value" },
+              },
+            ],
+          },
+        }),
+        "not defined in",
+      );
+    });
   });
 
   describe("force: variables", () => {

package/src/linter/featureSchema.ts

@@ -1465,15 +1465,9 @@ export function getFeatureZodSchema(
         }
       }
 
-      if (!value.variablesSchema) {
-        return;
-      }
-
-      // Every variable value is validated against its schema from variablesSchema. Sources covered:
-      // 1. variablesSchema[key].defaultValue  2. variablesSchema[key].disabledValue
-      // 3. variations[n].variables[key]       4. variations[n].variableOverrides[key][].value
-      // 5. rules[env][n].variables[key]       6. force[env][n].variables[key]
-      const variableSchemaByKey = value.variablesSchema;
+      // When variablesSchema is absent, variableSchemaByKey is {} so any variable key used in
+      // rules/force/variations will be reported as "not defined in variablesSchema".
+      const variableSchemaByKey = value.variablesSchema ?? {};
       const variationValues: string[] = [];
 
       if (value.variations) {
@@ -1482,100 +1476,102 @@ export function getFeatureZodSchema(
         });
       }
 
-      // variablesSchema[key]
-      const variableKeys = Object.keys(variableSchemaByKey);
-      variableKeys.forEach((variableKey) => {
-        const variableSchema = variableSchemaByKey[variableKey];
+      // variablesSchema[key] — only when feature defines variablesSchema
+      if (value.variablesSchema) {
+        const variableKeys = Object.keys(variableSchemaByKey);
+        variableKeys.forEach((variableKey) => {
+          const variableSchema = variableSchemaByKey[variableKey];
 
-        // When variable references a schema by name, ensure it resolves and validate the referenced schema
-        if ("schema" in variableSchema && variableSchema.schema) {
-          const resolvedSchema = resolveVariableSchema(
-            variableSchema as Parameters<typeof resolveVariableSchema>[0],
-            schemasByKey,
-          );
-          if (!resolvedSchema) {
-            ctx.addIssue({
-              code: z.ZodIssueCode.custom,
-              message: `Schema "${variableSchema.schema}" could not be loaded for variable "${variableKey}".`,
-              path: ["variablesSchema", variableKey],
-            });
-          } else {
-            refineRequiredKeysInSchema(
-              resolvedSchema as SchemaLikeForRequired,
-              ["variablesSchema", variableKey],
-              ctx,
+          // When variable references a schema by name, ensure it resolves and validate the referenced schema
+          if ("schema" in variableSchema && variableSchema.schema) {
+            const resolvedSchema = resolveVariableSchema(
+              variableSchema as Parameters<typeof resolveVariableSchema>[0],
               schemasByKey,
             );
+            if (!resolvedSchema) {
+              ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `Schema "${variableSchema.schema}" could not be loaded for variable "${variableKey}".`,
+                path: ["variablesSchema", variableKey],
+              });
+            } else {
+              refineRequiredKeysInSchema(
+                resolvedSchema as SchemaLikeForRequired,
+                ["variablesSchema", variableKey],
+                ctx,
+                schemasByKey,
+              );
+            }
           }
-        }
-
-        // When type and enum are both present, all enum values must match the type
-        const effectiveSchema = resolveVariableSchema(variableSchema, schemasByKey);
-        if (
-          effectiveSchema &&
-          effectiveSchema.type &&
-          Array.isArray(effectiveSchema.enum) &&
-          effectiveSchema.enum.length > 0
-        ) {
-          refineEnumMatchesType(
-            effectiveSchema as Parameters<typeof refineEnumMatchesType>[0],
-            ["variablesSchema", variableKey],
-            ctx,
-          );
-        }
 
-        // Inline variable schemas: validate minimum/maximum, minLength/maxLength/pattern, minItems/maxItems/uniqueItems
-        if (!("schema" in variableSchema) || !variableSchema.schema) {
-          const pathPrefix = ["variablesSchema", variableKey];
-          refineMinimumMaximum(
-            variableSchema as Parameters<typeof refineMinimumMaximum>[0],
-            pathPrefix,
-            ctx,
-          );
-          refineStringLengthPattern(
-            variableSchema as Parameters<typeof refineStringLengthPattern>[0],
-            pathPrefix,
-            ctx,
-          );
-          refineArrayItems(
-            variableSchema as Parameters<typeof refineArrayItems>[0],
-            pathPrefix,
-            ctx,
-          );
-        }
+          // When type and enum are both present, all enum values must match the type
+          const effectiveSchema = resolveVariableSchema(variableSchema, schemasByKey);
+          if (
+            effectiveSchema &&
+            effectiveSchema.type &&
+            Array.isArray(effectiveSchema.enum) &&
+            effectiveSchema.enum.length > 0
+          ) {
+            refineEnumMatchesType(
+              effectiveSchema as Parameters<typeof refineEnumMatchesType>[0],
+              ["variablesSchema", variableKey],
+              ctx,
+            );
+          }
 
-        if (variableKey === "variation") {
-          ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            message: `Variable key "${variableKey}" is reserved and cannot be used.`,
-            path: ["variablesSchema", variableKey],
-          });
-        }
+          // Inline variable schemas: validate minimum/maximum, minLength/maxLength/pattern, minItems/maxItems/uniqueItems
+          if (!("schema" in variableSchema) || !variableSchema.schema) {
+            const pathPrefix = ["variablesSchema", variableKey];
+            refineMinimumMaximum(
+              variableSchema as Parameters<typeof refineMinimumMaximum>[0],
+              pathPrefix,
+              ctx,
+            );
+            refineStringLengthPattern(
+              variableSchema as Parameters<typeof refineStringLengthPattern>[0],
+              pathPrefix,
+              ctx,
+            );
+            refineArrayItems(
+              variableSchema as Parameters<typeof refineArrayItems>[0],
+              pathPrefix,
+              ctx,
+            );
+          }
 
-        // defaultValue
-        superRefineVariableValue(
-          projectConfig,
-          variableSchema,
-          variableSchema.defaultValue,
-          ["variablesSchema", variableKey, "defaultValue"],
-          ctx,
-          variableKey,
-          schemasByKey,
-        );
+          if (variableKey === "variation") {
+            ctx.addIssue({
+              code: z.ZodIssueCode.custom,
+              message: `Variable key "${variableKey}" is reserved and cannot be used.`,
+              path: ["variablesSchema", variableKey],
+            });
+          }
 
-        // disabledValue (only when present)
-        if (variableSchema.disabledValue !== undefined) {
+          // defaultValue
           superRefineVariableValue(
             projectConfig,
             variableSchema,
-            variableSchema.disabledValue,
-            ["variablesSchema", variableKey, "disabledValue"],
+            variableSchema.defaultValue,
+            ["variablesSchema", variableKey, "defaultValue"],
             ctx,
             variableKey,
             schemasByKey,
           );
-        }
-      });
+
+          // disabledValue (only when present)
+          if (variableSchema.disabledValue !== undefined) {
+            superRefineVariableValue(
+              projectConfig,
+              variableSchema,
+              variableSchema.disabledValue,
+              ["variablesSchema", variableKey, "disabledValue"],
+              ctx,
+              variableKey,
+              schemasByKey,
+            );
+          }
+        });
+      }
 
       // variations: validate variation.variables and variation.variableOverrides (each value against its variable schema)
       if (value.variations) {