feat: avoid circular refs by omitting the "refs" property of files wh…

…en accessed from another file's refs.

README.md

@@ -83,7 +83,7 @@ When @metalsmith/refs runs, it will substitute the refs with the actual files:
 }
 ```
 
-The references are _references_, and not _clones_ of the targets they refer to, i.e. they will stay in sync when other plugins alter them later.
+The file references are _shallowly cloned_ from the targets they refer to _at the moment they are accessed_, i.e. they will be in sync when other plugins alter them later. To avoid circular references, you cannot access `file.refs.otherFile.refs`.
 
 As the example above shows, @metalsmith/refs will also add an `id` property to each processed file, unless you define an [explicit id](#custom-ids). By default the `id` is the file's path relative to metalsmith.source(), and with backslashes converted to forward slashes for cross-platform compatibility.
 

src/index.js

@@ -80,12 +80,35 @@ function refs(options) {
             file.refs[name] = resolved
             break
           case 'file':
-            resolved = srcRelPath(dirname(path), lookup)
-            file.refs[name] = files[resolved]
+            resolved = files[srcRelPath(dirname(path), lookup)]
+            if (resolved) {
+              Object.defineProperty(file.refs, name, {
+                get() {
+                  // eslint-disable-next-line no-unused-vars
+                  const { refs, ...allOthers } = resolved
+                  return allOthers
+                },
+                set(newRef) {
+                  resolved = newRef
+                }
+              })
+            }
             break
           case 'id':
             resolved = fileList.find((f) => f[1].id === lookup)
-            file.refs[name] = resolved[1]
+            if (resolved) {
+              resolved = resolved[1]
+              Object.defineProperty(file.refs, name, {
+                get() {
+                  // eslint-disable-next-line no-unused-vars
+                  const { refs, ...allOthers } = resolved
+                  return allOthers
+                },
+                set(newRef) {
+                  resolved = newRef
+                }
+              })
+            }
             break
           default:
             done(

test/fixtures/fixed-ref/expected/one-deep/index.json

@@ -1,3 +1,8 @@
 {
-  "id": "some-custom-id"
+  "id": "some-custom-id",
+  "refs": {
+    "mainscript": {
+      "id": "script"
+    }
+  }
 }

test/fixtures/fixed-ref/expected/script.json

@@ -1,8 +1,8 @@
 {
+  "id": "script",
   "refs": {
     "oneDeep": {
       "id": "some-custom-id"
     }
-  },
-  "id": "script.js"
+  }
 }

test/fixtures/fixed-ref/src/one-deep/index.html

@@ -1,3 +1,5 @@
 ---
 id: some-custom-id
+refs:
+  mainscript: id:script
 ---

test/fixtures/fixed-ref/src/script.js

@@ -1,4 +1,5 @@
 ---
+id: script
 # a ref to the HTML page contents
 refs:
   oneDeep: id:some-custom-id

test/fixtures/relative-refs/expected/about/index.json

@@ -2,6 +2,9 @@
   "refs": {
     "home": {
       "id": "index.html"
+    },
+    "deeplyNested": {
+      "id": "some/deeply/nested/file.html"
     }
   },
   "id": "about/index.html"

test/fixtures/relative-refs/expected/index.json

@@ -1,3 +1,8 @@
 {
+  "refs": {
+    "deeplyNested": {
+      "id": "some/deeply/nested/file.html"
+    }
+  },
   "id": "index.html"
 }

test/fixtures/relative-refs/expected/some/deeply/nested/file.json

@@ -0,0 +1,8 @@
+{
+  "refs": {
+    "about": {
+      "id": "about/index.html"
+    }
+  },
+  "id": "some/deeply/nested/file.html"
+}

test/fixtures/relative-refs/src/about/index.html

@@ -1,4 +1,5 @@
 ---
 refs:
   home: file:../index.html
+  deeplyNested: ../some/deeply/nested/file.html
 ---

test/fixtures/relative-refs/src/index.html

@@ -0,0 +1,4 @@
+---
+refs:
+  deeplyNested: some/deeply/nested/file.html
+---

test/fixtures/relative-refs/src/some/deeply/nested/file.html

@@ -0,0 +1,4 @@
+---
+refs:
+  about: ../../../about/index.html
+---

test/index.js

@@ -54,6 +54,11 @@ describe('@metalsmith/refs', function () {
     equals(fixture('absolute-refs/build'), fixture('absolute-refs/expected'))
   })
 
+  it('should resolve relative and circular refs', async function () {
+    await Metalsmith(fixture('relative-refs')).env('DEBUG', process.env.DEBUG).use(plugin()).use(toJSON).build()
+    equals(fixture('relative-refs/build'), fixture('relative-refs/expected'))
+  })
+
   it('should resolve refs as "file:" when no protocol is given', async function () {
     await Metalsmith(fixture('protocol-file-shortcut'))
       .env('DEBUG', process.env.DEBUG)