@featurevisor/core 2.13.0 → 2.15.0

package/src/builder/mutator.ts

@@ -0,0 +1,237 @@
+import type { VariableSchema, VariableValue } from "@featurevisor/types";
+
+export type PathPart =
+  | { key: string }
+  | { key: string; index: number }
+  | { key: string; selector: { prop: string; value: string } };
+
+export type MutationOperation = "set" | "append" | "prepend" | "after" | "before" | "remove";
+
+export interface ParsedNotation {
+  segments: PathPart[];
+  operation: MutationOperation;
+}
+
+export function parseNotation(notation: string): ParsedNotation {
+  let rest = notation.trim();
+  const operationMatch = rest.match(/:((?:append|prepend|after|before|remove))$/);
+  const operation: MutationOperation = operationMatch
+    ? (operationMatch[1] as MutationOperation)
+    : "set";
+  if (operationMatch) {
+    rest = rest.slice(0, -operationMatch[0].length);
+  }
+
+  const segments: PathPart[] = [];
+  let i = 0;
+  while (i < rest.length) {
+    let key = "";
+    while (i < rest.length && rest[i] !== "." && rest[i] !== "[") {
+      key += rest[i];
+      i++;
+    }
+    key = key.trim();
+    if (key) {
+      if (rest[i] === "[") {
+        i++;
+        const bracketStart = i;
+        while (i < rest.length && rest[i] !== "]") i++;
+        const bracketContent = rest.slice(bracketStart, i);
+        i++;
+        const eq = bracketContent.indexOf("=");
+        if (eq >= 0) {
+          const prop = bracketContent.slice(0, eq).trim();
+          let val = bracketContent.slice(eq + 1).trim();
+          if (val.startsWith('"') && val.endsWith('"')) val = val.slice(1, -1);
+          else if (val.startsWith("'") && val.endsWith("'")) val = val.slice(1, -1);
+          segments.push({ key, selector: { prop, value: val } });
+        } else {
+          const index = parseInt(bracketContent.trim(), 10);
+          segments.push({ key, index });
+        }
+      } else {
+        segments.push({ key });
+      }
+    } else if (rest[i] === "[") {
+      i++;
+      const bracketStart = i;
+      while (i < rest.length && rest[i] !== "]") i++;
+      const bracketContent = rest.slice(bracketStart, i);
+      i++;
+      const eq = bracketContent.indexOf("=");
+      if (eq >= 0) {
+        const prop = bracketContent.slice(0, eq).trim();
+        let val = bracketContent.slice(eq + 1).trim();
+        if (val.startsWith('"') && val.endsWith('"')) val = val.slice(1, -1);
+        else if (val.startsWith("'") && val.endsWith("'")) val = val.slice(1, -1);
+        segments.push({ key: "", selector: { prop, value: val } });
+      } else {
+        const index = parseInt(bracketContent.trim(), 10);
+        segments.push({ key: "", index });
+      }
+    }
+    if (rest[i] === ".") i++;
+  }
+
+  return { segments, operation };
+}
+
+function getAtSegment(obj: VariableValue, seg: PathPart): VariableValue {
+  if (obj === null || obj === undefined) return undefined;
+  const o = obj as Record<string, unknown>;
+  if ("index" in seg) {
+    const arr =
+      seg.key === ""
+        ? Array.isArray(obj)
+          ? obj
+          : undefined
+        : Array.isArray(obj)
+          ? obj
+          : (o[seg.key] as unknown[]);
+    if (!Array.isArray(arr)) return undefined;
+    return arr[seg.index] as VariableValue;
+  }
+  if ("selector" in seg) {
+    const arr =
+      seg.key === ""
+        ? Array.isArray(obj)
+          ? obj
+          : undefined
+        : Array.isArray(obj)
+          ? obj
+          : (o[seg.key] as unknown[]);
+    if (!Array.isArray(arr)) return undefined;
+    const { prop, value } = seg.selector;
+    const found = arr.find((item) => {
+      if (item === null || typeof item !== "object") return false;
+      const v = (item as Record<string, unknown>)[prop];
+      return String(v) === value;
+    });
+    return found as VariableValue;
+  }
+  return o[seg.key] as VariableValue;
+}
+
+function setAtSegment(
+  obj: Record<string, unknown> | unknown[],
+  seg: PathPart,
+  _value: VariableValue,
+  op: MutationOperation,
+  setValue: VariableValue | undefined,
+): void {
+  if ("index" in seg) {
+    const i = seg.index;
+    const arr =
+      seg.key === ""
+        ? Array.isArray(obj)
+          ? obj
+          : undefined
+        : Array.isArray(obj)
+          ? obj
+          : ((obj as Record<string, unknown>)[seg.key] as unknown[]);
+    if (!Array.isArray(arr)) return;
+    if (op === "remove") {
+      arr.splice(i, 1);
+      return;
+    }
+    if (op === "set") {
+      arr[i] = setValue;
+      return;
+    }
+    return;
+  }
+  if ("selector" in seg) {
+    const arr =
+      seg.key === ""
+        ? Array.isArray(obj)
+          ? obj
+          : undefined
+        : Array.isArray(obj)
+          ? obj
+          : ((obj as Record<string, unknown>)[seg.key] as unknown[]);
+    if (!Array.isArray(arr)) return;
+    const { prop, value: selVal } = seg.selector;
+    const numVal = /^\d+$/.test(selVal) ? parseInt(selVal, 10) : null;
+    const idx = arr.findIndex((item) => {
+      if (item === null || typeof item !== "object") return false;
+      const v = (item as Record<string, unknown>)[prop];
+      return String(v) === selVal || (numVal !== null && v === numVal);
+    });
+    if (idx < 0) return;
+    if (op === "remove") {
+      arr.splice(idx, 1);
+      return;
+    }
+    if (op === "after" && setValue !== undefined) {
+      arr.splice(idx + 1, 0, setValue);
+      return;
+    }
+    if (op === "before" && setValue !== undefined) {
+      arr.splice(idx, 0, setValue);
+      return;
+    }
+    return;
+  }
+  const key = seg.key;
+  const o = obj as Record<string, unknown>;
+  if (op === "remove") {
+    delete o[key];
+    return;
+  }
+  if (op === "append" && setValue !== undefined) {
+    const arr = (o[key] ?? []) as unknown[];
+    arr.push(setValue);
+    o[key] = arr;
+    return;
+  }
+  if (op === "prepend" && setValue !== undefined) {
+    const arr = (o[key] ?? []) as unknown[];
+    arr.unshift(setValue);
+    o[key] = arr;
+    return;
+  }
+  if (op === "set") {
+    o[key] = setValue as unknown;
+  }
+}
+
+export function mutate(
+  _schema: VariableSchema,
+  value: VariableValue,
+  notation: string,
+  setValue: VariableValue | undefined,
+): VariableValue {
+  if (value === null || value === undefined) return value;
+  const result = JSON.parse(JSON.stringify(value)) as VariableValue;
+
+  const { segments, operation } = parseNotation(notation);
+  if (segments.length === 0) {
+    if (Array.isArray(result) && setValue !== undefined) {
+      const arr = result as VariableValue[];
+      if (operation === "append") {
+        arr.push(setValue);
+        return result;
+      }
+      if (operation === "prepend") {
+        arr.unshift(setValue);
+        return result;
+      }
+    }
+    return result;
+  }
+
+  const last = segments[segments.length - 1];
+  const parentSegments = segments.slice(0, -1);
+
+  let container: Record<string, unknown> | unknown[] = result as
+    | Record<string, unknown>
+    | unknown[];
+  for (const seg of parentSegments) {
+    const next = getAtSegment(container as VariableValue, seg);
+    if (next === undefined) return result;
+    container = next as Record<string, unknown> | unknown[];
+  }
+
+  setAtSegment(container, last, undefined, operation, setValue);
+  return result;
+}

package/src/config/projectConfig.spec.ts

@@ -0,0 +1,31 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+
+import { getProjectConfig, ENVIRONMENTS_DIRECTORY_NAME } from "./projectConfig";
+
+function createTempProject(configBody: string) {
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "featurevisor-project-config-"));
+  fs.writeFileSync(path.join(tempRoot, "featurevisor.config.js"), configBody, "utf8");
+  return tempRoot;
+}
+
+describe("core: projectConfig", () => {
+  it("sets splitByEnvironment=false and environmentsDirectoryPath by default", () => {
+    const root = createTempProject("module.exports = {};");
+    const config = getProjectConfig(root);
+
+    expect(config.splitByEnvironment).toBe(false);
+    expect(config.environmentsDirectoryPath).toBe(path.join(root, ENVIRONMENTS_DIRECTORY_NAME));
+  });
+
+  it("throws when splitByEnvironment=true and environments=false", () => {
+    const root = createTempProject(
+      "module.exports = { splitByEnvironment: true, environments: false };",
+    );
+
+    expect(() => getProjectConfig(root)).toThrow(
+      "Invalid configuration: splitByEnvironment=true requires environments to be an array",
+    );
+  });
+});

package/src/config/projectConfig.ts

@@ -18,6 +18,7 @@ export const DATAFILES_DIRECTORY_NAME = "datafiles";
 export const DATAFILE_NAME_PATTERN = "featurevisor-%s.json";
 export const REVISION_FILE_NAME = "REVISION";
 export const SITE_EXPORT_DIRECTORY_NAME = "out";
+export const ENVIRONMENTS_DIRECTORY_NAME = "environments";
 
 export const CONFIG_MODULE_NAME = "featurevisor.config.js";
 export const ROOT_DIR_PLACEHOLDER = "<rootDir>";
@@ -52,8 +53,10 @@ export interface ProjectConfig {
   datafileNamePattern: string;
   revisionFileName: string;
   siteExportDirectoryPath: string;
+  environmentsDirectoryPath: string;
 
   environments: string[] | false;
+  splitByEnvironment: boolean;
   tags: string[];
   scopes?: Scope[];
 
@@ -91,6 +94,7 @@ export function getProjectConfig(rootDirectoryPath: string): ProjectConfig {
     adapter: FilesystemAdapter,
 
     featuresDirectoryPath: path.join(rootDirectoryPath, FEATURES_DIRECTORY_NAME),
+    environmentsDirectoryPath: path.join(rootDirectoryPath, ENVIRONMENTS_DIRECTORY_NAME),
     segmentsDirectoryPath: path.join(rootDirectoryPath, SEGMENTS_DIRECTORY_NAME),
     attributesDirectoryPath: path.join(rootDirectoryPath, ATTRIBUTES_DIRECTORY_NAME),
     groupsDirectoryPath: path.join(rootDirectoryPath, GROUPS_DIRECTORY_NAME),
@@ -104,6 +108,7 @@ export function getProjectConfig(rootDirectoryPath: string): ProjectConfig {
 
     enforceCatchAllRule: false,
     plugins: [],
+    splitByEnvironment: false,
 
     maxVariableStringLength: undefined,
     maxVariableArrayStringifiedLength: undefined,
@@ -136,6 +141,12 @@ export function getProjectConfig(rootDirectoryPath: string): ProjectConfig {
     finalConfig.parser = parsers[finalConfig.parser];
   }
 
+  if (finalConfig.splitByEnvironment && finalConfig.environments === false) {
+    throw new Error(
+      "Invalid configuration: splitByEnvironment=true requires environments to be an array",
+    );
+  }
+
   return finalConfig as ProjectConfig;
 }
 

package/src/datasource/adapter.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
 import type {
   DatafileContent,
   EnvironmentKey,
@@ -17,6 +18,13 @@ export interface DatafileOptions {
   datafilesDir?: string;
 }
 
+export type FeatureEnvironmentProperty = "rules" | "force" | "expose";
+
+export interface FeatureSourcePaths {
+  baseFilePath: string;
+  environmentFilePaths: Record<string, string>;
+}
+
 export abstract class Adapter {
   // entities
   abstract listEntities(entityType: EntityType): Promise<string[]>;
@@ -47,4 +55,17 @@ export abstract class Adapter {
     entityType?: EntityType,
     entityKey?: string,
   ): Promise<Commit>;
+
+  // feature source helpers (used by lint/history attribution)
+  async getFeatureSourcePaths(_featureKey: string): Promise<FeatureSourcePaths | undefined> {
+    return undefined;
+  }
+
+  async getFeaturePropertySourcePath(
+    _featureKey: string,
+    _property: FeatureEnvironmentProperty,
+    _environment?: string,
+  ): Promise<string | undefined> {
+    return undefined;
+  }
 }

package/src/datasource/datasource.ts

@@ -18,7 +18,12 @@ import type {
 import { ProjectConfig } from "../config";
 import { CustomParser } from "../parsers";
 
-import { Adapter, DatafileOptions } from "./adapter";
+import {
+  Adapter,
+  DatafileOptions,
+  FeatureEnvironmentProperty,
+  FeatureSourcePaths,
+} from "./adapter";
 
 export class Datasource {
   private adapter: Adapter;
@@ -93,6 +98,18 @@ export class Datasource {
     return this.adapter.deleteEntity("feature", featureKey);
   }
 
+  getFeatureSourcePaths(featureKey: FeatureKey): Promise<FeatureSourcePaths | undefined> {
+    return this.adapter.getFeatureSourcePaths(featureKey);
+  }
+
+  getFeaturePropertySourcePath(
+    featureKey: FeatureKey,
+    property: FeatureEnvironmentProperty,
+    environment?: string,
+  ): Promise<string | undefined> {
+    return this.adapter.getFeaturePropertySourcePath(featureKey, property, environment);
+  }
+
   async getRequiredFeaturesChain(
     featureKey: FeatureKey,
     chain = new Set<FeatureKey>(),

package/src/datasource/filesystemAdapter.spec.ts

@@ -0,0 +1,153 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+
+import { getProjectConfig } from "../config";
+import { Datasource } from "./datasource";
+
+function writeFile(filePath: string, content: string) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content, "utf8");
+}
+
+function createSplitProject(configBody: string) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "featurevisor-fs-adapter-"));
+  writeFile(path.join(root, "featurevisor.config.js"), configBody);
+
+  return root;
+}
+
+describe("core: filesystemAdapter (splitByEnvironment)", () => {
+  it("merges environment files into readFeature output", async () => {
+    const root = createSplitProject(
+      "module.exports = { environments: ['staging', 'production'], splitByEnvironment: true };",
+    );
+
+    writeFile(
+      path.join(root, "features", "checkout.yml"),
+      [
+        "key: checkout",
+        "description: Checkout feature",
+        "tags:",
+        "  - all",
+        "bucketBy: userId",
+      ].join("\n"),
+    );
+
+    writeFile(
+      path.join(root, "environments", "staging", "checkout.yml"),
+      ["rules:", "  - key: everyone", "    segments: '*'", "    percentage: 100"].join("\n"),
+    );
+
+    writeFile(
+      path.join(root, "environments", "production", "checkout.yml"),
+      [
+        "rules:",
+        "  - key: everyone",
+        "    segments: '*'",
+        "    percentage: 0",
+        "expose: false",
+      ].join("\n"),
+    );
+
+    const config = getProjectConfig(root);
+    const datasource = new Datasource(config, root);
+    const feature = await datasource.readFeature("checkout");
+    const rulesByEnvironment = feature.rules as Record<string, any[]>;
+    const exposeByEnvironment = feature.expose as Record<string, unknown>;
+
+    expect(rulesByEnvironment?.staging?.[0]?.percentage).toBe(100);
+    expect(rulesByEnvironment?.production?.[0]?.percentage).toBe(0);
+    expect(exposeByEnvironment?.production).toBe(false);
+  });
+
+  it("throws when any environment feature file is missing", async () => {
+    const root = createSplitProject(
+      "module.exports = { environments: ['staging', 'production'], splitByEnvironment: true };",
+    );
+
+    writeFile(
+      path.join(root, "features", "myFeature.yml"),
+      ["key: myFeature", "description: My feature", "tags:", "  - all", "bucketBy: userId"].join(
+        "\n",
+      ),
+    );
+
+    writeFile(
+      path.join(root, "environments", "staging", "myFeature.yml"),
+      ["rules:", "  - key: everyone", "    segments: '*'", "    percentage: 100"].join("\n"),
+    );
+
+    const config = getProjectConfig(root);
+    const datasource = new Datasource(config, root);
+
+    await expect(datasource.readFeature("myFeature")).rejects.toMatchObject({
+      featurevisorFilePath: expect.stringContaining(
+        path.join("environments", "production", "myFeature.yml"),
+      ),
+    });
+  });
+
+  it("throws when base feature file still defines rules in split mode", async () => {
+    const root = createSplitProject(
+      "module.exports = { environments: ['staging'], splitByEnvironment: true };",
+    );
+
+    writeFile(
+      path.join(root, "features", "foo.yml"),
+      [
+        "key: foo",
+        "description: Foo",
+        "tags:",
+        "  - all",
+        "bucketBy: userId",
+        "rules:",
+        "  staging:",
+        "    - key: everyone",
+        "      segments: '*'",
+        "      percentage: 100",
+      ].join("\n"),
+    );
+
+    writeFile(
+      path.join(root, "environments", "staging", "foo.yml"),
+      ["rules:", "  - key: everyone", "    segments: '*'", "    percentage: 100"].join("\n"),
+    );
+
+    const config = getProjectConfig(root);
+    const datasource = new Datasource(config, root);
+
+    await expect(datasource.readFeature("foo")).rejects.toThrow(
+      "base file must not define rules, force, or expose when splitByEnvironment=true",
+    );
+  });
+
+  it("throws when environment file has unknown keys", async () => {
+    const root = createSplitProject(
+      "module.exports = { environments: ['staging'], splitByEnvironment: true };",
+    );
+
+    writeFile(
+      path.join(root, "features", "foo.yml"),
+      ["key: foo", "description: Foo", "tags:", "  - all", "bucketBy: userId"].join("\n"),
+    );
+
+    writeFile(
+      path.join(root, "environments", "staging", "foo.yml"),
+      [
+        "rules:",
+        "  - key: everyone",
+        "    segments: '*'",
+        "    percentage: 100",
+        "extraKey: not allowed",
+      ].join("\n"),
+    );
+
+    const config = getProjectConfig(root);
+    const datasource = new Datasource(config, root);
+
+    await expect(datasource.readFeature("foo")).rejects.toThrow(
+      "Unknown key(s) in environment feature file: extraKey",
+    );
+  });
+});