feat: sdk parity (#2)

Author: fahad19

.editorconfig

@@ -12,3 +12,6 @@ trim_trailing_whitespace = true
 [*.java]
 insert_final_newline = true
 indent_size = 4
+
+[Makefile]
+indent_style = tab

.gitignore

@@ -66,5 +66,8 @@ build/
 out/
 dist/
 example-1/
+monorepo
+featurevisor-go
+specs
 
 .flattened-pom.xml

Makefile

@@ -0,0 +1,50 @@
+.PHONY: install build test setup-monorepo update-monorepo setup-golang-sdk update-golang-sdk setup-references update-references
+
+install:
+	mvn install
+
+build:
+	mvn compile package
+
+test:
+	mvn test
+
+##
+# Monorepo
+#
+setup-monorepo:
+	mkdir -p monorepo
+	if [ ! -d "monorepo/.git" ]; then \
+		git clone git@github.com:featurevisor/featurevisor.git monorepo; \
+	else \
+		(cd monorepo && git fetch origin main && git checkout main && git pull origin main); \
+	fi
+	make update-monorepo
+
+update-monorepo:
+	(cd monorepo && git pull origin main && make install && make build)
+
+##
+# Golang SDK
+#
+setup-golang-sdk:
+	mkdir -p featurevisor-go
+	if [ ! -d "featurevisor-go/.git" ]; then \
+		git clone git@github.com:featurevisor/featurevisor-go.git featurevisor-go; \
+	else \
+		(cd featurevisor-go && git fetch origin main && git checkout main && git pull origin main); \
+	fi
+
+update-golang-sdk:
+	(cd featurevisor-go && git pull origin main)
+
+##
+# All references
+#
+setup-references:
+	make setup-monorepo
+	make setup-golang-sdk
+
+update-references:
+	make update-monorepo
+	make update-golang-sdk

README.md

@@ -303,15 +303,64 @@ f.<MyCustomClass>getVariableObject(featureKey, variableKey, context);
 
 f.<Map<String, Object>>getVariableJSON(featureKey, variableKey, context);
 f.<MyCustomClass>getVariableJSON(featureKey, variableKey, context);
+f.getVariableJSONNode(featureKey, variableKey, context);
 ```
 
+For strongly typed decoding, additional overloads are available:
+
+```java
+import com.fasterxml.jackson.core.type.TypeReference;
+
+// Array decoding using Class<T>
+List<MyItem> items = f.getVariableArray(featureKey, variableKey, context, MyItem.class);
+
+// Array decoding using TypeReference
+List<Map<String, Object>> rows = f.getVariableArray(
+    featureKey,
+    variableKey,
+    context,
+    new TypeReference<List<Map<String, Object>>>() {}
+);
+
+// Object decoding using Class<T>
+MyConfig config = f.getVariableObject(featureKey, variableKey, context, MyConfig.class);
+
+// Object decoding using TypeReference
+Map<String, List<MyConfig>> nested = f.getVariableObject(
+    featureKey,
+    variableKey,
+    context,
+    new TypeReference<Map<String, List<MyConfig>>>() {}
+);
+```
+
+Typed overloads are additive and non-breaking. If decoding fails for the requested target type, these methods return `null`.
+
+For dynamic JSON values with unknown shape, use `getVariableJSONNode`:
+
+```java
+import com.fasterxml.jackson.databind.JsonNode;
+
+JsonNode node = f.getVariableJSONNode(featureKey, variableKey, context);
+
+if (node != null && node.isObject()) {
+    String nested = node.path("key").path("nested").asText(null);
+}
+```
+
+If a variable schema type is `json` and the resolved value is a malformed stringified JSON, JSON parsing fails safely and these methods return `null`:
+
+- `getVariable(...)`
+- `getVariableJSONNode(...)`
+- `getVariableJSON(...)`
+
 ## Getting all evaluations
 
 You can get evaluations of all features available in the SDK instance:
 
 ```java
-import com.featurevisor.types.EvaluatedFeatures;
-import com.featurevisor.types.EvaluatedFeature;
+import com.featurevisor.sdk.EvaluatedFeatures;
+import com.featurevisor.sdk.EvaluatedFeature;
 
 EvaluatedFeatures allEvaluations = f.getAllEvaluations(context);
 
@@ -690,6 +739,7 @@ Similar to parent SDK, child instances also support several additional methods:
 - `getVariableArray`
 - `getVariableObject`
 - `getVariableJSON`
+- `getVariableJSONNode`
 - `getAllEvaluations`
 - `on`
 - `close`
@@ -717,9 +767,16 @@ $ mvn exec:java -Dexec.mainClass="com.featurevisor.cli.CLI" -Dexec.args="test --
 Additional options that are available:
 
 ```bash
-$ mvn exec:java -Dexec.mainClass="com.featurevisor.cli.CLI" -Dexec.args="test --projectDirectoryPath=/absolute/path/to/your/featurevisor/project --quiet --onlyFailures --keyPattern=myFeatureKey --assertionPattern=#1"
+$ mvn exec:java -Dexec.mainClass="com.featurevisor.cli.CLI" -Dexec.args="test --projectDirectoryPath=/absolute/path/to/your/featurevisor/project --quiet --onlyFailures --keyPattern=myFeatureKey --assertionPattern=#1 --with-tags --with-scopes --showDatafile --schemaVersion=2 --inflate=1"
 ```
 
+Scoped and tagged test behavior mirrors the JavaScript tester:
+
+- `--with-tags`: builds and tests assertions against tagged datafiles.
+- `--with-scopes`: builds scoped datafiles and tests scoped assertions against those scoped files.
+- without `--with-scopes`: scoped assertions still run by merging scope context into assertion context (fallback behavior).
+- if both `scope` and `tag` are present in an assertion, scope datafile takes precedence.
+
 ### Benchmark
 
 Learn more about benchmarking [here](https://featurevisor.com/docs/cli/#benchmarking).