@featurevisor/core 2.26.1 → 3.0.1

package/src/builder/buildProject.ts

@@ -1,19 +1,22 @@
-import { SCHEMA_VERSION, ProjectConfig } from "../config";
+import * as path from "path";
+
+import { ProjectConfig } from "../config";
 import { Datasource } from "../datasource";
 
 import { getNextRevision } from "./revision";
 import { buildDatafile, getCustomDatafile } from "./buildDatafile";
-import { buildScopedDatafile } from "./buildScopedDatafile";
+import { applyContextToDatafile } from "./applyContextToDatafile";
 import { Dependencies } from "../dependencies";
 import { Plugin } from "../cli";
-import type { Scope } from "../config";
 
-import type { DatafileContent } from "@featurevisor/types";
+import type { DatafileContent, Target } from "@featurevisor/types";
+import { assertProjectSetJsonSelection, getProjectSetExecutions, printSetHeader } from "../sets";
+import { CLI_COLOR_CYAN, CLI_FORMAT_BOLD, CLI_FORMAT_GREEN, colorize } from "../tester/cliFormat";
+import { resolveTargets } from "../targeting";
 
 export interface BuildCLIOptions {
   revision?: string;
   revisionFromHash?: boolean;
-  schemaVersion?: string;
 
   // all three together
   environment?: string;
@@ -24,8 +27,8 @@ export interface BuildCLIOptions {
   inflate?: number;
   datafilesDir?: string;
 
-  tag?: string;
-  scope?: string; // scope name only
+  target?: string | string[];
+  set?: string;
 }
 
 function getFeaturevisorVersion(): string {
@@ -39,91 +42,53 @@ function getFeaturevisorVersion(): string {
   }
 }
 
+function getEnvironmentLabel(environment: string | false) {
+  return environment === false ? "No environment" : `Environment "${environment}"`;
+}
+
 async function buildForEnvironment({
   projectConfig,
   datasource,
   nextRevision,
   environment,
-  tags,
-  scopes,
+  targets,
   cliOptions,
 }: {
   projectConfig: ProjectConfig;
   datasource: Datasource;
   nextRevision: string;
   environment: string | false;
-  tags: string[];
-  scopes?: Scope[];
+  targets: Array<Target & { key: string }>;
   cliOptions: BuildCLIOptions;
 }) {
-  console.log(`\nBuilding datafiles for environment: ${environment}`);
+  console.log("");
+  console.log(CLI_FORMAT_BOLD, getEnvironmentLabel(environment));
 
   const existingState = await datasource.readState(environment);
   const featurevisorVersion = getFeaturevisorVersion();
 
-  // by tag
-  for (const tag of tags) {
-    console.log(`\n  => Tag: ${tag}`);
+  for (const target of targets) {
+    console.log(`  ${colorize("Target", CLI_COLOR_CYAN)}: ${target.key}`);
 
-    const datafileContent = await buildDatafile(
+    const datafileContent = await buildTargetDatafile({
       projectConfig,
       datasource,
-      {
-        schemaVersion: cliOptions.schemaVersion || SCHEMA_VERSION,
-        revision: nextRevision,
-        revisionFromHash: cliOptions.revisionFromHash,
-        environment: environment,
-        tag: tag,
-        inflate: cliOptions.inflate,
-        featurevisorVersion,
-      },
+      target,
+      environment,
       existingState,
-    );
+      revision: nextRevision,
+      revisionFromHash: cliOptions.revisionFromHash,
+      inflate: cliOptions.inflate,
+      featurevisorVersion,
+    });
 
-    // write datafile for environment/tag
-    await datasource.writeDatafile(datafileContent as DatafileContent, {
+    await datasource.writeDatafile(datafileContent, {
       environment,
-      tag,
+      target: target.key,
       datafilesDir: cliOptions.datafilesDir,
     });
   }
 
-  // by scope
-  if (scopes) {
-    for (const scope of scopes) {
-      console.log(`\n  => Scope: ${scope.name}`);
-
-      const datafileContent = await buildDatafile(
-        projectConfig,
-        datasource,
-        {
-          schemaVersion: cliOptions.schemaVersion || SCHEMA_VERSION,
-          revision: nextRevision,
-          revisionFromHash: cliOptions.revisionFromHash,
-          environment: environment,
-          tag: scope.tag,
-          tags: scope.tags,
-          inflate: cliOptions.inflate,
-          featurevisorVersion,
-        },
-        existingState,
-      );
-
-      const scopedDatafileContent = buildScopedDatafile(
-        datafileContent as DatafileContent,
-        scope.context,
-      );
-
-      // write scoped datafile
-      await datasource.writeDatafile(scopedDatafileContent, {
-        environment,
-        tag: scope.tag,
-        scope: scope,
-        datafilesDir: cliOptions.datafilesDir,
-      });
-    }
-  }
-
   if (typeof cliOptions.stateFiles === "undefined" || cliOptions.stateFiles) {
     // write state for environment
     await datasource.writeState(environment, existingState);
@@ -133,6 +98,51 @@ async function buildForEnvironment({
   }
 }
 
+export async function buildTargetDatafile({
+  projectConfig,
+  datasource,
+  target,
+  environment,
+  existingState,
+  revision,
+  revisionFromHash,
+  inflate,
+  featurevisorVersion,
+}: {
+  projectConfig: ProjectConfig;
+  datasource: Datasource;
+  target: Target;
+  environment: string | false;
+  existingState: Awaited<ReturnType<Datasource["readState"]>>;
+  revision: string;
+  revisionFromHash?: boolean;
+  inflate?: number;
+  featurevisorVersion?: string;
+}): Promise<DatafileContent> {
+  const datafileContent = await buildDatafile(
+    projectConfig,
+    datasource,
+    {
+      revision,
+      revisionFromHash,
+      environment,
+      tag: target.tag,
+      tags: target.tags,
+      includeFeatures: target.includeFeatures,
+      excludeFeatures: target.excludeFeatures,
+      inflate,
+      featurevisorVersion,
+    },
+    existingState,
+  );
+
+  if (target.context) {
+    return applyContextToDatafile(datafileContent as DatafileContent, target.context);
+  }
+
+  return datafileContent as DatafileContent;
+}
+
 export async function buildProject(deps: Dependencies, cliOptions: BuildCLIOptions = {}) {
   const { projectConfig, datasource } = deps;
 
@@ -146,24 +156,38 @@ export async function buildProject(deps: Dependencies, cliOptions: BuildCLIOptio
    * This way we centralize the datafile generation in one place,
    * while tests can be run anywhere else.
    */
-  if (cliOptions.environment && cliOptions.json) {
-    const scope = cliOptions.scope
-      ? projectConfig.scopes?.find((scope) => scope.name === cliOptions.scope)
-      : undefined;
+  if (cliOptions.json) {
+    const environment = cliOptions.environment || false;
+
+    if (Array.isArray(projectConfig.environments) && !cliOptions.environment) {
+      throw new Error("Pass --environment=<environment> when printing a datafile.");
+    }
+
+    const targets = await resolveTargets(datasource, cliOptions.target, {
+      defaultToAll: false,
+      requireTargets: false,
+    });
+    if (targets.length > 1) {
+      throw new Error("Only one --target can be used with --json or --print.");
+    }
+    const target = targets[0];
 
     let datafileContent = await getCustomDatafile({
       featureKey: cliOptions.feature,
-      environment: cliOptions.environment,
+      environment,
       projectConfig,
       datasource,
       revision: cliOptions.revision,
-      schemaVersion: cliOptions.schemaVersion,
-      tag: cliOptions.tag,
-      tags: scope?.tags,
+      inflate: cliOptions.inflate,
+      tag: target?.tag,
+      tags: target?.tags,
+      includeFeatures: target?.includeFeatures,
+      excludeFeatures: target?.excludeFeatures,
+      featurevisorVersion: getFeaturevisorVersion(),
     });
 
-    if (scope) {
-      datafileContent = buildScopedDatafile(datafileContent as DatafileContent, scope.context);
+    if (target?.context) {
+      datafileContent = applyContextToDatafile(datafileContent as DatafileContent, target.context);
     }
 
     if (cliOptions.pretty) {
@@ -178,10 +202,13 @@ export async function buildProject(deps: Dependencies, cliOptions: BuildCLIOptio
   /**
    * Regular build process that writes to disk.
    */
-  const { tags, environments, scopes } = projectConfig;
+  const { environments } = projectConfig;
+  const targets = await resolveTargets(datasource, cliOptions.target);
 
   const currentRevision = await datasource.readRevision();
-  console.log("\nCurrent revision:", currentRevision);
+  console.log("");
+  console.log(CLI_FORMAT_BOLD, "Building Featurevisor datafiles");
+  console.log(`  Current revision: ${currentRevision}`);
 
   const nextRevision =
     (cliOptions.revision && cliOptions.revision.toString()) || getNextRevision(currentRevision);
@@ -194,33 +221,91 @@ export async function buildProject(deps: Dependencies, cliOptions: BuildCLIOptio
         datasource,
         nextRevision,
         environment,
-        tags,
-        scopes,
+        targets,
         cliOptions,
       });
     }
   }
 
   // no environment
-  if (environments === false) {
+  if (!Array.isArray(environments)) {
     await buildForEnvironment({
       projectConfig,
       datasource,
       nextRevision,
       environment: false,
-      tags,
-      scopes,
+      targets,
       cliOptions,
     });
   }
 
-  console.log("\nLatest revision:", nextRevision);
+  console.log("");
+  console.log(CLI_FORMAT_GREEN, "Datafiles built");
+  console.log(CLI_FORMAT_BOLD, `Latest revision: ${nextRevision}`);
+}
+
+export async function buildProjectSets(deps: Dependencies, cliOptions: BuildCLIOptions = {}) {
+  const { projectConfig, datasource } = deps;
+
+  assertProjectSetJsonSelection(projectConfig, cliOptions.set, cliOptions.json);
+
+  const executions = await getProjectSetExecutions(projectConfig, datasource, cliOptions.set);
+  const currentRevision = await datasource.readRevision();
+  const nextRevision =
+    (cliOptions.revision && cliOptions.revision.toString()) || getNextRevision(currentRevision);
+
+  if (projectConfig.sets && !cliOptions.json) {
+    console.log("");
+    console.log(CLI_FORMAT_BOLD, "Building Featurevisor sets");
+    console.log(`  Sets: ${executions.map((execution) => execution.set).join(", ")}`);
+    console.log(`  Current project revision: ${currentRevision}`);
+  }
+
+  for (const execution of executions) {
+    printSetHeader(projectConfig, execution.set, cliOptions.json);
+
+    const executionCliOptions =
+      projectConfig.sets && cliOptions.datafilesDir
+        ? {
+            ...cliOptions,
+            datafilesDir: path.join(cliOptions.datafilesDir, execution.set),
+          }
+        : cliOptions;
+
+    await buildProject(
+      {
+        ...deps,
+        projectConfig: execution.projectConfig,
+        datasource: execution.datasource,
+      },
+      {
+        ...executionCliOptions,
+        revision: projectConfig.sets ? nextRevision : cliOptions.revision,
+      },
+    );
+  }
+
+  if (
+    projectConfig.sets &&
+    !cliOptions.json &&
+    (typeof cliOptions.stateFiles === "undefined" || cliOptions.stateFiles) &&
+    !cliOptions.revision
+  ) {
+    await datasource.writeRevision(nextRevision);
+    console.log("");
+    console.log(CLI_FORMAT_GREEN, "Featurevisor sets built");
+    console.log(CLI_FORMAT_BOLD, `Latest project revision: ${nextRevision}`);
+  }
 }
 
 export const buildPlugin: Plugin = {
   command: "build",
   handler: async function ({ rootDirectoryPath, projectConfig, datasource, parsed }) {
-    await buildProject(
+    if (parsed.print) {
+      parsed.json = true;
+    }
+
+    await buildProjectSets(
       {
         rootDirectoryPath,
         projectConfig,
@@ -233,7 +318,7 @@ export const buildPlugin: Plugin = {
   examples: [
     {
       command: "build",
-      description: "build datafiles for all environments and tags",
+      description: "build datafiles for all environments and targets",
     },
     {
       command: "build --revision=123",
@@ -244,7 +329,7 @@ export const buildPlugin: Plugin = {
       description: "build datafiles for production environment",
     },
     {
-      command: "build --print --environment=production --feature=featureKey",
+      command: "build --print --environment=production --feature=featureKey --target=web",
       description: "print datafile for a feature in production environment",
     },
     {

package/src/builder/buildRuntimeDatafiles.ts

@@ -0,0 +1,57 @@
+import type { DatafileContent } from "@featurevisor/types";
+
+import type { Dependencies } from "../dependencies";
+import { resolveTargets } from "../targeting";
+import { buildDatafile } from "./buildDatafile";
+import { buildTargetDatafile } from "./buildProject";
+
+export interface RuntimeDatafile {
+  target?: string;
+  datafile: DatafileContent;
+}
+
+export async function buildRuntimeDatafiles(
+  deps: Dependencies,
+  options: {
+    environment: string | false;
+    target?: string | string[];
+    revision: string;
+    inflate?: number;
+  },
+): Promise<RuntimeDatafile[]> {
+  const { projectConfig, datasource } = deps;
+  const existingState = await datasource.readState(options.environment);
+  const targets = await resolveTargets(datasource, options.target, {
+    defaultToAll: false,
+    requireTargets: false,
+  });
+
+  if (targets.length === 0) {
+    const datafile = await buildDatafile(
+      projectConfig,
+      datasource,
+      {
+        revision: options.revision,
+        environment: options.environment,
+        inflate: options.inflate,
+      },
+      existingState,
+    );
+    return [{ datafile }];
+  }
+
+  return Promise.all(
+    targets.map(async (target) => ({
+      target: target.key,
+      datafile: await buildTargetDatafile({
+        projectConfig,
+        datasource,
+        target,
+        environment: options.environment,
+        existingState,
+        revision: options.revision,
+        inflate: options.inflate,
+      }),
+    })),
+  );
+}

package/src/builder/index.ts

@@ -1,3 +1,2 @@
 export * from "./buildDatafile";
-export * from "./buildScopedDatafile";
 export * from "./buildProject";

package/src/cli/cli.ts

@@ -51,11 +51,6 @@ export async function runCLI(runnerOptions: RunnerOptions) {
     y = y.command({
       command: plugin.command,
       handler: async function (parsed: ParsedOptions) {
-        // @NOTE: in future, allow yargs options to be defined via plugins
-        if (parsed.schemaVersion && typeof parsed.schemaVersion !== "string") {
-          parsed.schemaVersion = parsed.schemaVersion.toString();
-        }
-
         try {
           const result = await plugin.handler({
             rootDirectoryPath,

package/src/cli/plugins.ts

@@ -1,4 +1,5 @@
 import type { Plugin } from "./cli";
+import { createCatalogPlugin } from "@featurevisor/catalog";
 
 import { initPlugin } from "../init";
 import { lintPlugin } from "../linter";
@@ -13,7 +14,8 @@ import { evaluatePlugin } from "../evaluate";
 import { assessDistributionPlugin } from "../assess-distribution";
 import { infoPlugin } from "../info";
 import { listPlugin } from "../list";
-import { sitePlugin } from "../site";
+import { promotePlugin } from "../promoter";
+import { getProjectSetExecutions } from "../sets";
 
 // that do not require an existing project
 export const nonProjectPlugins: Plugin[] = [initPlugin];
@@ -32,7 +34,10 @@ export const projectBasedPlugins: Plugin[] = [
   assessDistributionPlugin,
   infoPlugin,
   listPlugin,
-  sitePlugin,
+  promotePlugin,
+  createCatalogPlugin({
+    getProjectSetExecutions,
+  }),
 ];
 
 export const commonPlugins: Plugin[] = [];

package/src/config/projectConfig.spec.ts

@@ -2,7 +2,12 @@ import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
 
-import { getProjectConfig, ENVIRONMENTS_DIRECTORY_NAME } from "./projectConfig";
+import {
+  getProjectConfig,
+  getProjectConfigForSet,
+  SETS_DIRECTORY_NAME,
+  TARGETS_DIRECTORY_NAME,
+} from "./projectConfig";
 
 function createTempProject(configBody: string) {
   const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "featurevisor-project-config-"));
@@ -11,21 +16,179 @@ function createTempProject(configBody: string) {
 }
 
 describe("core: projectConfig", () => {
-  it("sets splitByEnvironment=false and environmentsDirectoryPath by default", () => {
+  it("sets project defaults", () => {
     const root = createTempProject("module.exports = {};");
     const config = getProjectConfig(root);
 
-    expect(config.splitByEnvironment).toBe(false);
-    expect(config.environmentsDirectoryPath).toBe(path.join(root, ENVIRONMENTS_DIRECTORY_NAME));
+    expect(config.environments).toBeUndefined();
+    expect(config.namespaceCharacter).toBe(".");
+    expect(config.sets).toBe(false);
+    expect(config.promotionFlows).toBeUndefined();
+    expect(config.setsDirectoryPath).toBe(path.join(root, SETS_DIRECTORY_NAME));
+    expect(config.targetsDirectoryPath).toBe(path.join(root, TARGETS_DIRECTORY_NAME));
+    expect("scopes" in config).toBe(false);
+    expect("siteExportDirectoryPath" in config).toBe(false);
   });
 
-  it("throws when splitByEnvironment=true and environments=false", () => {
+  it("silently ignores obsolete scopes configuration", () => {
     const root = createTempProject(
-      "module.exports = { splitByEnvironment: true, environments: false };",
+      'module.exports = { scopes: [{ name: "web", context: { platform: "web" } }] };',
     );
+    const config = getProjectConfig(root);
+
+    expect("scopes" in config).toBe(false);
+  });
+
+  it("throws when sets is not boolean", () => {
+    const root = createTempProject("module.exports = { sets: 'yes' };");
+
+    expect(() => getProjectConfig(root)).toThrow("Invalid sets: yes. It must be a boolean.");
+  });
+
+  it("accepts environments when it is an array of strings", () => {
+    const root = createTempProject('module.exports = { environments: ["staging", "production"] };');
+    const config = getProjectConfig(root);
+
+    expect(config.environments).toEqual(["staging", "production"]);
+  });
+
+  it("throws when environments is present but not an array of strings", () => {
+    const cases = [
+      {
+        config: "module.exports = { environments: false };",
+        message: "Invalid environments: false. It must be an array of strings when defined.",
+      },
+      {
+        config: 'module.exports = { environments: "production" };',
+        message: "Invalid environments: production. It must be an array of strings when defined.",
+      },
+      {
+        config: "module.exports = { environments: { production: true } };",
+        message:
+          "Invalid environments: [object Object]. It must be an array of strings when defined.",
+      },
+      {
+        config: 'module.exports = { environments: ["production", 1] };',
+        message: "Invalid environments[1]: 1. It must be a string.",
+      },
+    ];
+
+    for (const testCase of cases) {
+      const root = createTempProject(testCase.config);
+
+      expect(() => getProjectConfig(root)).toThrow(testCase.message);
+    }
+  });
+
+  it("accepts custom namespaceCharacter values including slash", () => {
+    const root = createTempProject('module.exports = { namespaceCharacter: "/" };');
+    const config = getProjectConfig(root);
+
+    expect(config.namespaceCharacter).toBe("/");
+  });
+
+  it("throws when namespaceCharacter is not a non-empty string", () => {
+    const cases = [
+      {
+        config: "module.exports = { namespaceCharacter: '' };",
+        message: "Invalid namespaceCharacter: . It must be a non-empty string.",
+      },
+      {
+        config: "module.exports = { namespaceCharacter: 1 };",
+        message: "Invalid namespaceCharacter: 1. It must be a non-empty string.",
+      },
+    ];
+
+    for (const testCase of cases) {
+      const root = createTempProject(testCase.config);
 
-    expect(() => getProjectConfig(root)).toThrow(
-      "Invalid configuration: splitByEnvironment=true requires environments to be an array",
+      expect(() => getProjectConfig(root)).toThrow(testCase.message);
+    }
+  });
+
+  it("accepts valid promotionFlows object rules", () => {
+    const root = createTempProject(
+      [
+        "module.exports = {",
+        "  promotionFlows: [",
+        '    { from: "dev", to: "staging" },',
+        '    { from: "staging", to: "production" },',
+        "  ],",
+        "};",
+        "",
+      ].join("\n"),
+    );
+
+    const config = getProjectConfig(root);
+
+    expect(config.promotionFlows).toEqual([
+      { from: "dev", to: "staging" },
+      { from: "staging", to: "production" },
+    ]);
+  });
+
+  it("rejects invalid promotionFlows shapes", () => {
+    const cases = [
+      {
+        config: "module.exports = { promotionFlows: true };",
+        message: "Invalid promotionFlows: true. It must be an array.",
+      },
+      {
+        config: 'module.exports = { promotionFlows: ["dev"] };',
+        message:
+          'Invalid promotionFlows[0]: dev. Each entry must be an object with exactly "from" and "to" string fields.',
+      },
+      {
+        config: 'module.exports = { promotionFlows: [{ from: "dev" }] };',
+        message:
+          'Invalid promotionFlows[0]: {"from":"dev"}. Each entry must contain exactly "from" and "to".',
+      },
+      {
+        config:
+          'module.exports = { promotionFlows: [{ from: "dev", to: "staging", note: true }] };',
+        message:
+          'Invalid promotionFlows[0]: {"from":"dev","to":"staging","note":true}. Each entry must contain exactly "from" and "to".',
+      },
+      {
+        config: 'module.exports = { promotionFlows: [{ from: "dev", to: 1 }] };',
+        message:
+          'Invalid promotionFlows[0]: {"from":"dev","to":1}. "from" and "to" must be strings.',
+      },
+    ];
+
+    for (const testCase of cases) {
+      const root = createTempProject(testCase.config);
+
+      expect(() => getProjectConfig(root)).toThrow(testCase.message);
+    }
+  });
+
+  it("remaps project config paths for a set", () => {
+    const root = createTempProject("module.exports = { sets: true };");
+    const config = getProjectConfig(root);
+    const setConfig = getProjectConfigForSet(config, "staging");
+    const setRoot = path.join(root, "sets", "staging");
+
+    expect(setConfig.featuresDirectoryPath).toBe(path.join(setRoot, "features"));
+    expect(setConfig.environments).toBeUndefined();
+    expect(setConfig.namespaceCharacter).toBe(".");
+    expect(setConfig.segmentsDirectoryPath).toBe(path.join(setRoot, "segments"));
+    expect(setConfig.attributesDirectoryPath).toBe(path.join(setRoot, "attributes"));
+    expect(setConfig.groupsDirectoryPath).toBe(path.join(setRoot, "groups"));
+    expect(setConfig.schemasDirectoryPath).toBe(path.join(setRoot, "schemas"));
+    expect(setConfig.targetsDirectoryPath).toBe(path.join(setRoot, "targets"));
+    expect(setConfig.testsDirectoryPath).toBe(path.join(setRoot, "tests"));
+    expect(setConfig.stateDirectoryPath).toBe(path.join(root, ".featurevisor", "sets", "staging"));
+    expect(setConfig.datafilesDirectoryPath).toBe(path.join(root, "datafiles", "staging"));
+  });
+
+  it("preserves configured environments when remapping project config for a set", () => {
+    const root = createTempProject(
+      'module.exports = { sets: true, environments: ["staging", "production"] };',
     );
+    const config = getProjectConfig(root);
+    const setConfig = getProjectConfigForSet(config, "staging");
+
+    expect(setConfig.environments).toEqual(["staging", "production"]);
   });
 });