@featurevisor/core 2.6.7 → 2.8.0

package/src/linter/testSchema.ts

@@ -84,7 +84,15 @@ export function getTestsZodSchema(
                   }),
                 )
               : z.never().optional(),
-            // @TODO: add tag later, similar to `scope` below
+            tag: z
+              .string()
+              .refine(
+                (value) => projectConfig.tags.includes(value),
+                (value) => ({
+                  message: `Unknown tag "${value}"`,
+                }),
+              )
+              .optional(),
             scope: z
               .string()
               .refine(

package/src/list/matrix.ts

@@ -101,7 +101,10 @@ export function applyCombinationToFeatureAssertion(
     flattenedAssertion.scope = applyCombinationToValue(flattenedAssertion.scope, combination);
   }
 
-  // @TODO: support `tag` later, similar to `scope` above
+  // tag
+  if (flattenedAssertion.tag) {
+    flattenedAssertion.tag = applyCombinationToValue(flattenedAssertion.tag, combination);
+  }
 
   return flattenedAssertion;
 }

package/src/parsers/index.ts

@@ -0,0 +1,22 @@
+import { jsonParser } from "./json";
+import { ymlParser } from "./yml";
+
+export interface CustomParser {
+  extension: string;
+  parse: <T>(content: string, filePath?: string) => T;
+  stringify: (content: any, filePath?: string) => string;
+}
+
+/**
+ * If we want to add more built-in parsers,
+ * add them to this object with new file extension as the key,
+ * and a function that takes file content as string and returns parsed object as the value.
+ */
+export const parsers: { [key: string]: CustomParser } = {
+  yml: ymlParser,
+  json: jsonParser,
+};
+
+export type BuiltInParser = keyof typeof parsers; // keys of parsers object
+
+export type Parser = BuiltInParser | CustomParser;

package/src/parsers/json.spec.ts

@@ -0,0 +1,36 @@
+import { jsonParser } from "./json";
+
+describe("core :: parser :: jsonParser", () => {
+  it("should parse JSON string into object", () => {
+    const jsonString = '{"foo":1,"bar":"baz","arr":[1,2]}';
+    const result = jsonParser.parse<{ foo: number; bar: string; arr: number[] }>(jsonString);
+    expect(result).toEqual({ foo: 1, bar: "baz", arr: [1, 2] });
+  });
+
+  it("should stringify object into JSON string (pretty-printed)", () => {
+    const obj = { foo: 1, bar: "baz", arr: [1, 2] };
+    const jsonString = jsonParser.stringify(obj);
+    const expectedString = `{
+  "foo": 1,
+  "bar": "baz",
+  "arr": [
+    1,
+    2
+  ]
+}`;
+    expect(jsonString).toBe(expectedString);
+  });
+
+  it("should parse and then stringify to preserve content", () => {
+    const original = { alpha: "a", num: 42, bool: true, nullish: null, nested: { z: "x" } };
+    const str = jsonParser.stringify(original);
+    const reparsed = jsonParser.parse<typeof original>(str);
+    expect(reparsed).toEqual(original);
+  });
+
+  it("should throw if invalid JSON string is provided to parse", () => {
+    expect(() => {
+      jsonParser.parse("this is not json");
+    }).toThrow();
+  });
+});

package/src/parsers/json.ts

@@ -0,0 +1,11 @@
+import type { CustomParser } from "./index";
+
+export const jsonParser: CustomParser = {
+  extension: "json",
+  parse: function <T>(content: string): T {
+    return JSON.parse(content) as T;
+  },
+  stringify: function (content: any) {
+    return JSON.stringify(content, null, 2);
+  },
+};

package/src/parsers/yml.spec.ts

@@ -0,0 +1,174 @@
+import { ymlParser } from "./yml";
+
+describe("core :: parser :: ymlParser", () => {
+  it("should parse YAML string into object", () => {
+    const yamlString = `
+foo: 1
+bar: baz
+arr:
+  - 1
+  - 2
+`;
+    const result = ymlParser.parse<{ foo: number; bar: string; arr: number[] }>(yamlString);
+    expect(result).toEqual({ foo: 1, bar: "baz", arr: [1, 2] });
+  });
+
+  it("should stringify object into YAML string", () => {
+    const obj = { foo: 1, bar: "baz", arr: [1, 2] };
+    const yamlString = ymlParser.stringify(obj);
+    expect(yamlString.trim()).toBe(`foo: 1
+bar: baz
+arr:
+  - 1
+  - 2`);
+  });
+
+  it("should parse and then stringify to preserve YAML content semantically", () => {
+    const original = {
+      alpha: "a",
+      num: 42,
+      bool: true,
+      nullish: null,
+      nested: { z: "x", y: [1, 2] },
+    };
+    const str = ymlParser.stringify(original);
+    const reparsed = ymlParser.parse<typeof original>(str);
+    expect(reparsed).toEqual(original);
+  });
+
+  it("should throw if invalid YAML string is provided to parse", () => {
+    expect(() => {
+      ymlParser.parse("foo: : bar");
+    }).toThrow();
+  });
+
+  describe("stringify() with filePath argument (existing file for ordering/comments only)", () => {
+    const fs = require("fs");
+    const path = require("path");
+    const os = require("os");
+
+    let tempFile: string;
+
+    beforeEach(() => {
+      tempFile = path.join(os.tmpdir(), `test_${Math.random()}.yml`);
+    });
+
+    afterEach(() => {
+      if (fs.existsSync(tempFile)) {
+        fs.unlinkSync(tempFile);
+      }
+    });
+
+    it("should save exactly the new object; existing file is only for ordering/comments", () => {
+      const beforeYaml =
+        `
+foo: 1 # foo comment here
+extra: blah
+
+##
+# Comment above nested
+#
+nested:
+  a: x
+  b: y # b comment
+array:
+  - one # one
+  - two # two
+  - three # three
+`.trim() + "\n";
+
+      const newContent = {
+        foo: 42,
+        bar: "new",
+        nested: { b: "updated", c: "added" },
+        array: ["two", "three", "four"],
+      };
+
+      const afterYaml =
+        `
+foo: 42 # foo comment here
+bar: new
+##
+# Comment above nested
+#
+nested:
+  b: updated # b comment
+  c: added
+array:
+  - two # two
+  - three # three
+  - four
+`.trim() + "\n";
+
+      fs.writeFileSync(tempFile, beforeYaml);
+
+      const output = ymlParser.stringify(newContent, tempFile);
+
+      expect(output).toBe(afterYaml);
+    });
+
+    it("should replace the root if YAML file is empty", () => {
+      const beforeYaml = "";
+      const afterYaml =
+        `
+hello: world
+test:
+  - 1
+  - 2
+  - 3
+`.trim() + "\n";
+
+      fs.writeFileSync(tempFile, beforeYaml);
+
+      const obj = { hello: "world", test: [1, 2, 3] };
+      const output = ymlParser.stringify(obj, tempFile);
+
+      expect(output).toBe(afterYaml);
+    });
+
+    it("should throw if trying to set YAML document root to a primitive", () => {
+      const beforeYaml =
+        `
+foo: bar
+`.trim() + "\n";
+
+      fs.writeFileSync(tempFile, beforeYaml);
+
+      // Root must be an object when using filePath; primitives throw
+      expect(() => {
+        ymlParser.stringify("primitive", tempFile);
+      }).toThrow(/Cannot set root document to a primitive value/);
+    });
+
+    it("should fall back to simple stringify if filePath does not exist", () => {
+      const fakeFilePath = path.join(os.tmpdir(), `notfound_${Math.random()}.yml`);
+      const afterYaml =
+        `
+only: in-memory
+`.trim() + "\n";
+
+      const obj = { only: "in-memory" };
+      const output = ymlParser.stringify(obj, fakeFilePath);
+
+      expect(output).toBe(afterYaml);
+      expect(fs.existsSync(fakeFilePath)).toBe(false); // should not create the file
+    });
+
+    it("should not mutate the original YAML file", () => {
+      const beforeYaml =
+        `
+foo: unchanged
+bar: before
+`.trim() + "\n";
+
+      fs.writeFileSync(tempFile, beforeYaml);
+      const onDiskBefore = fs.readFileSync(tempFile, "utf8");
+
+      const obj = { bar: "after" };
+      ymlParser.stringify(obj, tempFile);
+
+      const onDiskAfter = fs.readFileSync(tempFile, "utf8");
+      expect(onDiskAfter).toBe(onDiskBefore); // file on disk unchanged
+    });
+  });
+});

package/src/parsers/yml.ts

@@ -0,0 +1,168 @@
+import * as fs from "fs";
+
+import { parse, parseDocument, stringify } from "yaml";
+import type { Pair, YAMLMap, YAMLSeq } from "yaml/types";
+import { Scalar as ScalarCtor } from "yaml/types";
+
+import type { CustomParser } from "./index";
+
+function getKeyString(keyNode: unknown): string | undefined {
+  if (keyNode == null) return undefined;
+  if (typeof (keyNode as { value?: unknown }).value !== "undefined") {
+    return String((keyNode as { value: unknown }).value);
+  }
+  return typeof keyNode === "string" ? keyNode : undefined;
+}
+
+function copyComments(source: Pair, target: Pair): void {
+  if (source.comment != null) target.comment = source.comment;
+  if (source.commentBefore != null) target.commentBefore = source.commentBefore;
+  const srcVal = source.value as
+    | { comment?: string | null; commentBefore?: string | null }
+    | undefined;
+  const tgtVal = target.value;
+  if (srcVal && tgtVal && typeof tgtVal === "object" && tgtVal !== null) {
+    const t = tgtVal as { comment?: string | null; commentBefore?: string | null };
+    if (srcVal.comment != null) t.comment = srcVal.comment;
+    if (srcVal.commentBefore != null) t.commentBefore = srcVal.commentBefore;
+  }
+}
+
+function isYamlMap(node: unknown): node is YAMLMap {
+  return node != null && typeof node === "object" && Array.isArray((node as YAMLMap).items);
+}
+
+function isYamlSeq(node: unknown): node is YAMLSeq {
+  return node != null && typeof node === "object" && Array.isArray((node as YAMLSeq).items);
+}
+
+function seqItemValueKey(item: unknown): string {
+  if (item == null) return String(item);
+  const n = item as { value?: unknown; toJSON?: () => unknown };
+  if (typeof n.value !== "undefined") return JSON.stringify(n.value);
+  if (typeof n.toJSON === "function") return JSON.stringify(n.toJSON());
+  return JSON.stringify(item);
+}
+
+function primitiveValueKey(v: unknown): string {
+  return JSON.stringify(v);
+}
+
+function createValueWithComments(
+  schema: { createNode: (v: unknown) => unknown; createPair: (k: unknown, v: unknown) => Pair },
+  oldNode: unknown,
+  newValue: unknown,
+): unknown {
+  if (newValue === null || typeof newValue !== "object") {
+    const node = new ScalarCtor(newValue);
+    const old = oldNode as { comment?: string | null; commentBefore?: string | null } | undefined;
+    if (old) {
+      if (old.comment != null) node.comment = old.comment;
+      if (old.commentBefore != null) node.commentBefore = old.commentBefore;
+    }
+    return node;
+  }
+  if (Array.isArray(newValue)) {
+    const oldSeq = isYamlSeq(oldNode) ? (oldNode as YAMLSeq) : null;
+    const oldItemsByValue = new Map<string, unknown>();
+    if (oldSeq && oldSeq.items) {
+      for (const item of oldSeq.items) {
+        oldItemsByValue.set(seqItemValueKey(item), item);
+      }
+    }
+    const newSeq = schema.createNode([]) as YAMLSeq;
+    for (const el of newValue) {
+      const oldItem = oldItemsByValue.get(primitiveValueKey(el));
+      const itemNode = createValueWithComments(schema, oldItem, el);
+      newSeq.add(itemNode);
+    }
+    return newSeq;
+  }
+  // newValue is a plain object; preserve comments from old map if present
+  const oldMap = isYamlMap(oldNode) ? (oldNode as YAMLMap) : null;
+  const oldPairsByKey = new Map<string, Pair>();
+  if (oldMap) {
+    for (const pair of (oldMap.items || []) as Pair[]) {
+      const keyStr = getKeyString(pair.key);
+      if (keyStr !== undefined) oldPairsByKey.set(keyStr, pair);
+    }
+  }
+  const newMap = schema.createNode({}) as YAMLMap;
+  const obj = newValue as Record<string, unknown>;
+  for (const k of Object.keys(obj)) {
+    const oldPair = oldPairsByKey.get(k);
+    const childOldNode = oldPair ? oldPair.value : undefined;
+    const childNewValue = createValueWithComments(schema, childOldNode, obj[k]);
+    const newPair = schema.createPair(k, childNewValue);
+    if (oldPair) copyComments(oldPair, newPair);
+    newMap.add(newPair);
+  }
+  const result = newMap as { comment?: string | null; commentBefore?: string | null };
+  const oldVal = oldNode as { comment?: string | null; commentBefore?: string | null } | undefined;
+  if (oldVal && result) {
+    if (oldVal.comment != null) result.comment = oldVal.comment;
+    if (oldVal.commentBefore != null) result.commentBefore = oldVal.commentBefore;
+  }
+  return result;
+}
+
+function replaceContentsPreservingComments(
+  doc: {
+    contents: unknown;
+    schema: { createNode: (v: unknown) => unknown; createPair: (k: unknown, v: unknown) => Pair };
+  },
+  newContent: Record<string, unknown>,
+): void {
+  const oldRoot = doc.contents as YAMLMap | null | undefined;
+  if (!oldRoot || !Array.isArray((oldRoot as YAMLMap).items)) {
+    doc.contents = doc.schema.createNode(newContent) as typeof doc.contents;
+    return;
+  }
+
+  const schema = doc.schema;
+  const oldPairsByKey = new Map<string, Pair>();
+  for (const pair of (oldRoot as YAMLMap).items as Pair[]) {
+    const keyStr = getKeyString(pair.key);
+    if (keyStr !== undefined) oldPairsByKey.set(keyStr, pair);
+  }
+
+  const newMap = schema.createNode({}) as YAMLMap;
+  for (const key of Object.keys(newContent)) {
+    const oldPair = oldPairsByKey.get(key);
+    const valueNode = createValueWithComments(schema, oldPair?.value, newContent[key]);
+    const newPair = schema.createPair(key, valueNode);
+    if (oldPair) copyComments(oldPair, newPair);
+    newMap.add(newPair);
+  }
+
+  (doc as { contents: unknown }).contents = newMap;
+}
+
+export const ymlParser: CustomParser = {
+  extension: "yml",
+  parse: function <T>(content: string): T {
+    return parse(content) as T;
+  },
+  stringify: function (content: any, filePath?: string) {
+    if (!filePath || !fs.existsSync(filePath)) {
+      return stringify(content);
+    }
+
+    const fileContent = fs.readFileSync(filePath, "utf8");
+    if (!fileContent.trim()) {
+      return stringify(content);
+    }
+
+    // newObject is the final saved object; existing file is only for ordering/comments
+    if (content === null || typeof content !== "object" || Array.isArray(content)) {
+      throw new Error("Cannot set root document to a primitive value");
+    }
+
+    const doc = parseDocument(fileContent) as {
+      contents: unknown;
+      schema: { createNode: (v: unknown) => unknown; createPair: (k: unknown, v: unknown) => Pair };
+    };
+    replaceContentsPreservingComments(doc, content);
+    return doc.toString();
+  },
+};

package/src/tester/testFeature.ts

@@ -61,12 +61,17 @@ export async function testFeature(
 
     let datafileContent = datafileContentByKey.get(assertion.environment || false);
 
+    // scope
     const scopedDatafileKey = `${assertion.environment}-scope-${assertion.scope}`;
     if (assertion.scope && datafileContentByKey.has(scopedDatafileKey)) {
       datafileContent = datafileContentByKey.get(scopedDatafileKey);
     }
 
-    // @TODO: do similar like `scope`, but for `tag`
+    // tag
+    const taggedDatafileKey = `${assertion.environment}-tag-${assertion.tag}`;
+    if (assertion.tag && datafileContentByKey.has(taggedDatafileKey)) {
+      datafileContent = datafileContentByKey.get(taggedDatafileKey);
+    }
 
     if (options.showDatafile) {
       console.log("");

package/src/tester/testProject.ts

@@ -23,6 +23,7 @@ export interface TestProjectOptions {
   schemaVersion?: string;
   inflate?: number;
   withScopes?: boolean;
+  withTags?: boolean;
 }
 
 export interface ExecutionResult {
@@ -173,7 +174,26 @@ export async function testProject(
         }
       }
 
-      // @TODO: by tag
+      // by tag
+      if (projectConfig.tags && options.withTags) {
+        for (const tag of projectConfig.tags) {
+          const existingState = await datasource.readState(environment);
+          const datafileContent = (await buildDatafile(
+            projectConfig,
+            datasource,
+            {
+              schemaVersion: options.schemaVersion || SCHEMA_VERSION,
+              revision: "include-tagged-features",
+              environment: environment,
+              inflate: options.inflate,
+              tag: tag,
+            },
+            existingState,
+          )) as DatafileContent;
+
+          datafileContentByKey.set(`${environment}-tag-${tag}`, datafileContent);
+        }
+      }
     }
   }
 
@@ -221,7 +241,26 @@ export async function testProject(
       }
     }
 
-    // @TODO: by tag
+    // by tag
+    if (projectConfig.tags && options.withTags) {
+      for (const tag of projectConfig.tags) {
+        const existingState = await datasource.readState(false);
+        const datafileContent = (await buildDatafile(
+          projectConfig,
+          datasource,
+          {
+            schemaVersion: options.schemaVersion || SCHEMA_VERSION,
+            revision: "include-tagged-features",
+            environment: false,
+            inflate: options.inflate,
+            tag: tag,
+          },
+          existingState,
+        )) as DatafileContent;
+
+        datafileContentByKey.set(`tag-${tag}`, datafileContent);
+      }
+    }
   }
 
   const tests = await listEntities<Test>(

package/src/utils/git.ts

@@ -2,7 +2,8 @@ import * as path from "path";
 
 import type { Commit, EntityDiff, EntityType } from "@featurevisor/types";
 
-import { CustomParser, ProjectConfig } from "../config";
+import { ProjectConfig } from "../config";
+import { CustomParser } from "../parsers";
 
 function parseGitCommitShowOutput(gitShowOutput: string) {
   const result = {