fix(extend): use given file path for token data

__tests__/extend.test.js

@@ -156,6 +156,21 @@ describe('extend', () => {
       expect(StyleDictionaryExtended.properties).toEqual(output);
     });
 
+    it('should use relative filePaths for the filePath property', () => {
+      var filePath = "__tests__/__properties/paddings.json";
+      var StyleDictionaryExtended = StyleDictionary.extend({
+        "source": [filePath]
+      });
+      var output = helpers.fileToJSON(__dirname + "/__properties/paddings.json");
+      traverseObj(output, (obj) => {
+        if (obj.value && !obj.filePath) {
+          obj.filePath = filePath;
+          obj.isSource = true;
+        }
+      });
+      expect(StyleDictionaryExtended.properties).toEqual(output);
+    });
+
     it('should override existing properties source is given', () => {
       var StyleDictionaryExtended = StyleDictionary.extend({
         properties: test_props,

docs/properties.md

@@ -109,4 +109,48 @@ You can organize and name your style properties however you want, **there are no
 
 Also, the CTI structure provides a good mechanism to target transforms for specific kinds of properties. All of the transforms provided by the framework use the CTI structure to know if it should be applied. For instance, the 'color/hex' transform only applies to properties of the category 'color'.
 
+## Default property metadata
+
+Style Dictionary adds some metadata on each property that helps with transforms and formats. Here is what Style Dictionary adds onto each property:
+
+| Attribute | Type | Description |
+| :--- | :--- | :--- |
+| name | String | A default name of the property that is set to the key of the property.
+| path | Array[String] | The object path of the property. `color: { background: primary: {value: "#fff"}}` will have a path of `['color','background', 'primary']`.
+| original | Object | A pristine copy of the original property object.
+| filePath | String | The relative file path of the file the token is defined in. 
+| isSource | Boolean | If the token is from a file in the `source` array as opposed to `include`.
+
+This:
+
+```json5
+{
+  "color": {
+    "background": {
+      "primary": { "value": "#fff" }
+    }
+  }
+}
+```
+
+becomes:
+
+```json5
+{
+  "color": {
+    "background": {
+      "primary": {
+        "name": "primary",
+        "path": ["color","background","primary"],
+        "original": {
+          "value": "#fff"
+        },
+        "filePath": "tokens/color/background.json",
+        "isSource": true
+      }
+    }
+  }
+}
+```
+
 ----

lib/utils/combineJSON.js

@@ -50,7 +50,8 @@ function combineJSON(arr, deep, collision, source, parsers=[]) {
   }
 
   for (i = 0; i < files.length; i++) {
-    var resolvedPath = resolveCwd(path.isAbsolute(files[i]) ? files[i] : './' + files[i]);
+    var filePath = files[i];
+    var resolvedPath = resolveCwd(path.isAbsolute(filePath) ? filePath : './' + filePath);
     var file_content = null;
 
     try {
@@ -80,7 +81,7 @@ function combineJSON(arr, deep, collision, source, parsers=[]) {
     // Add some side data on each property to make filtering easier
     traverseObj(file_content, (obj) => {
       if (obj.value && !obj.filePath) {
-        obj.filePath = resolvedPath;
+        obj.filePath = filePath;
 
         obj.isSource = source || source === undefined ? true : false;
       }