v0.17.1

* Improve dat.gui theme
* Zoom to fit canvas at start

.all-contributorsrc

@@ -752,6 +752,60 @@
       "contributions": [
         "code"
       ]
+    },
+    {
+      "login": "Laptop765",
+      "name": "Paul",
+      "avatar_url": "https://avatars.githubusercontent.com/u/1468359?v=4",
+      "profile": "https://github.com/Laptop765",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "eltociear",
+      "name": "Ikko Ashimine",
+      "avatar_url": "https://avatars.githubusercontent.com/u/22633385?v=4",
+      "profile": "https://bandism.net/",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "memeplex",
+      "name": "memeplex",
+      "avatar_url": "https://avatars.githubusercontent.com/u/2845433?v=4",
+      "profile": "https://github.com/memeplex",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "AndreiD049",
+      "name": "AndreiD049",
+      "avatar_url": "https://avatars.githubusercontent.com/u/52671223?v=4",
+      "profile": "https://github.com/AndreiD049",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "iam-yan",
+      "name": "Yan",
+      "avatar_url": "https://avatars.githubusercontent.com/u/48427014?v=4",
+      "profile": "https://github.com/iam-yan",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "jimt",
+      "name": "Jim Tittsler",
+      "avatar_url": "https://avatars.githubusercontent.com/u/180326?v=4",
+      "profile": "https://WikiEducator.org/User:JimTittsler",
+      "contributions": [
+        "doc"
+      ]
     }
   ],
   "contributorsPerLine": 7,

.eslintrc.json

@@ -1,20 +1,18 @@
 {
-    "root": true,
-    "parser": "@typescript-eslint/parser",
-    "parserOptions": {
-        "ecmaVersion": 6,
-        "sourceType": "module"
-    },
-    "plugins": [
-        "@typescript-eslint"
-    ],
-    "rules": {
-        "@typescript-eslint/class-name-casing": "warn",
-        "@typescript-eslint/semi": "warn",
-        "curly": "warn",
-        "eqeqeq": "warn",
-        "no-throw-literal": "warn",
-        "semi": "off",
-        "require-await": "warn"
-    }
+  "root": true,
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": 6,
+    "sourceType": "module"
+  },
+  "plugins": ["@typescript-eslint", "import"],
+  "rules": {
+    "@typescript-eslint/class-name-casing": "warn",
+    "@typescript-eslint/semi": "warn",
+    "curly": "warn",
+    "eqeqeq": "warn",
+    "no-throw-literal": "warn",
+    "semi": "off",
+    "require-await": "warn"
+  }
 }

.github/workflows/ci.yml

@@ -3,17 +3,15 @@ name: CI
 on:
   push:
     branches:
-      - '**'
-  # The following will also make the workflow run on all PRs, internal and external.
-  # This would create duplicate runs, that we are skipping by adding the "if" to the jobs below.
-  # See https://github.community/t/duplicate-checks-on-push-and-pull-request-simultaneous-event/18012
+      - master
   pull_request:
+    branches:
+      - master
 
 jobs:
   lint:
     name: Lint
     runs-on: ubuntu-18.04
-    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != 'foambubble/foam'
     steps:
       - uses: actions/checkout@v1
       - name: Setup Node
@@ -27,7 +25,7 @@ jobs:
             node_modules
             */*/node_modules
             packages/foam-vscode/.vscode-test
-          key: ${{ runner.os }}-${{ hashFiles('**/yarn.lock', 'packages/foam-vscode/src/test/run-tests.ts') }}
+          key: ${{ runner.os }}-${{ hashFiles('**/yarn.lock', 'packages/foam-vscode/src/test/run-tests.ts') }}-${{ secrets.CACHE_VERSION }}
       - name: Install Dependencies
         run: yarn
       - name: Check Lint Rules
@@ -39,7 +37,6 @@ jobs:
       matrix:
         os: [macos-10.15, ubuntu-18.04, windows-2019]
     runs-on: ${{ matrix.os }}
-    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != 'foambubble/foam'
     env:
       OS: ${{ matrix.os }}
     steps:
@@ -55,12 +52,12 @@ jobs:
             node_modules
             */*/node_modules
             packages/foam-vscode/.vscode-test
-          key: ${{ runner.os }}-${{ hashFiles('**/yarn.lock', 'packages/foam-vscode/src/test/run-tests.ts') }}
+          key: ${{ runner.os }}-${{ hashFiles('**/yarn.lock', 'packages/foam-vscode/src/test/run-tests.ts') }}-${{ secrets.CACHE_VERSION }}
       - name: Install Dependencies
         run: yarn
       - name: Build Packages
         run: yarn build
       - name: Run Tests
-        uses: GabrielBB/xvfb-action@v1.0
+        uses: GabrielBB/xvfb-action@v1.4
         with:
           run: yarn test

.vscode/launch.json

@@ -3,83 +3,29 @@
 // Hover to view descriptions of existing attributes.
 // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
 {
-	"version": "0.2.0",
-  "inputs": [
+  "version": "0.2.0",
+  "configurations": [
     {
-      "id": "packageName",
-      "type": "pickString",
-      "description": "Select the package in which this test is located",
-      "options": ["foam-core", "foam-vscode"],
-      "default": "foam-core"
+      "type": "node",
+      "name": "Debug Jest Tests",
+      "request": "launch",
+      "runtimeArgs": ["workspace", "foam-vscode", "run", "test"], // ${yarnWorkspaceName} is what we're missing
+      "args": ["--runInBand"],
+      "runtimeExecutable": "yarn",
+      "console": "integratedTerminal",
+      "internalConsoleOptions": "neverOpen",
+      "disableOptimisticBPs": true
+    },
+    {
+      "name": "Run VSCode Extension",
+      "type": "extensionHost",
+      "request": "launch",
+      "runtimeExecutable": "${execPath}",
+      "args": [
+        "--extensionDevelopmentPath=${workspaceFolder}/packages/foam-vscode"
+      ],
+      "outFiles": ["${workspaceFolder}/packages/foam-vscode/out/**/*.js"],
+      "preLaunchTask": "${defaultBuildTask}"
     }
-  ],
-	"configurations": [
-		{
-			"type": "node",
-			"name": "vscode-jest-tests",
-			"request": "launch",
-			"runtimeArgs": ["workspace", "${input:packageName}", "run", "test"], // ${yarnWorkspaceName} is what we're missing
-			"args": [
-					"--runInBand"
-			],
-			"runtimeExecutable": "yarn",
-			"console": "integratedTerminal",
-			"internalConsoleOptions": "neverOpen",
-			"disableOptimisticBPs": true,
-	},
-		{
-			"name": "Debug Jest Tests",
-			"type": "node",
-			"request": "launch",
-			"runtimeArgs": [
-				"--inspect-brk",
-				"${workspaceRoot}/node_modules/.bin/tsdx",
-				"test",
-			],
-			"console": "integratedTerminal",
-			"cwd": "${workspaceFolder}/packages/foam-core",
-			"internalConsoleOptions": "neverOpen"
-	},
-		{
-			"name": "Run VSCode Extension",
-			"type": "extensionHost",
-			"request": "launch",
-			"runtimeExecutable": "${execPath}",
-			"args": [
-				"--extensionDevelopmentPath=${workspaceFolder}/packages/foam-vscode"
-			],
-			"outFiles": [
-				"${workspaceFolder}/packages/foam-vscode/out/**/*.js"
-			],
-			"preLaunchTask": "${defaultBuildTask}"
-		},
-
-		// @NOTE: This task is broken. VSCode e2e tests are currently disabled
-		// due to incompability of jest and mocha inside a typescript monorepo
-		// Contributions to fix this are welcome!
-		{
-			"name": "Test VSCode Extension",
-			"type": "extensionHost",
-			"request": "launch",
-			"runtimeExecutable": "${execPath}",
-			"args": [
-				"--extensionDevelopmentPath=${workspaceFolder}/packages/foam-vscode",
-				"--extensionTestsPath=${workspaceFolder}/packages/foam-vscode/out/test/suite/index"
-			],
-			"outFiles": [
-				"${workspaceFolder}/packages/foam-vscode/out/test/**/*.js"
-			],
-			"preLaunchTask": "${defaultBuildTask}"
-		},
-		{
-			"name": "Test Core",
-			"type": "node",
-			"request": "launch",
-			"program": "${workspaceFolder}/node_modules/tsdx/dist/index.js",
-			"args": ["test"],
-			"cwd": "${workspaceFolder}/packages/foam-core",
-			"internalConsoleOptions": "openOnSessionStart",
-			"preLaunchTask": "${defaultBuildTask}"
-		}
-	]
+  ]
 }

.vscode/tasks.json

@@ -1,31 +1,31 @@
 // See https://go.microsoft.com/fwlink/?LinkId=733558
 // for the documentation about the tasks.json format
 {
-	"version": "2.0.0",
-	"tasks": [
-		{
-			"label": "watch: foam-vscode",
-			"type": "npm",
-			"script": "start:vscode",
-			"problemMatcher": "$tsc-watch",
-			"isBackground": true,
-			"presentation": {
-				"reveal": "always"
-			},
-			"group": {
-				"kind": "build",
-				"isDefault": true
-			}
-		},
-		{
-			"label": "test: all packages",
-			"type": "npm",
-			"script": "test",
-			"problemMatcher": [],
-			"group": {
-				"kind": "test",
-				"isDefault": true
-			},
-		}
-	]
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "watch: foam-vscode",
+      "type": "npm",
+      "script": "watch",
+      "problemMatcher": "$tsc-watch",
+      "isBackground": true,
+      "presentation": {
+        "reveal": "always"
+      },
+      "group": {
+        "kind": "build",
+        "isDefault": true
+      }
+    },
+    {
+      "label": "test: all packages",
+      "type": "npm",
+      "script": "test",
+      "problemMatcher": [],
+      "group": {
+        "kind": "test",
+        "isDefault": true
+      }
+    }
+  ]
 }

docs/contribution-guide.md

@@ -18,8 +18,6 @@ Before you start contributing we recommend that you read the following links:
 We understand that diving in an unfamiliar codebase may seem scary,
 to make it easier for new contributors we provide some resources:
 
-- [[architecture]] - This document describes the architecture of Foam and how the repository is structured.
-
 You can also see [existing issues](https://github.com/foambubble/foam/issues) and help out!
 Finally, the easiest way to help, is to use it and provide feedback by [submitting issues](https://github.com/foambubble/foam/issues/new/choose) or participating in the [Foam Community Discord](https://foambubble.github.io/join-discord/g)!
 
@@ -35,22 +33,48 @@ If you're interested in contributing, this short guide will help you get things
 
    `yarn install`
 
-3. This project uses [Yarn workspaces](https://classic.yarnpkg.com/en/docs/workspaces/). `foam-vscode` relies on `foam-core`. This means we need to compile it before we do any extension development. From the root, run the command:
+3. From the root, run the command:
 
    `yarn build`
 
 You should now be ready to start working!
 
+### Structure of the project
+
+Foam code and documentation live in the monorepo at [foambubble/foam](https://github.com/foambubble/foam/).
+
+- [/docs](https://github.com/foambubble/foam/tree/master/docs): documentation and [[recipes]].
+
+Exceptions to the monorepo are:
+
+- The starter template at [foambubble/foam-template](https://github.com/foambubble/)
+- All other [[recommended-extensions]] live in their respective GitHub repos
+
+This project uses [Yarn workspaces](https://classic.yarnpkg.com/en/docs/workspaces/). 
+
+Originally Foam had:
+
+- [/packages/foam-core](https://github.com/foambubble/foam/tree/master/packages/foam-core) - Powers the core functionality in Foam across all platforms.
+- [/packages/foam-vscode](https://github.com/foambubble/foam/tree/master/packages/foam-vscode) - The core VS Code plugin.
+
+To improve DX we have moved the `foam-core` module into `packages/foam-vscode/src/core`, but from a development point of view it's useful to think of the `foam-vscode/src/core` "submodule" as something that might be extracted in the future.
+
+For all intents and purposes this means two things:
+
+1. nothing in `foam-vscode/src/core` should depend on files outside of this directory
+2. code in `foam-vscode/src/core` should NOT depend on `vscode` library
+
+We have kept the yarn workspace for the time being as we might use it to pull out `foam-core` in the future, or we might need it for other packages that the VS Code plugin could depend upon (e.g. currently the graph visualization is inside the module, but it might be pulled out if its complexity increases).
+
 ### Testing
 
 Code needs to come with tests.
 We use the following convention in Foam:
 
-- *.test.ts are unit tests
-- *.spec.ts are integration tests
+- `*.test.ts` are unit tests
+- `*.spec.ts` are integration tests
 
-Also, note that tests in `foam-core` live in the `test` directory.
-Tests in `foam-vscode` live alongside the code in `src`.
+Tests live alongside the code in `src`.
 
 ### The VS Code Extension
 
@@ -71,5 +95,6 @@ Feel free to modify and submit a PR if this guide is out-of-date or contains err
 [//begin]: # "Autogenerated link references for markdown compatibility"
 [principles]: principles.md "Principles"
 [code-of-conduct]: code-of-conduct.md "Code of Conduct"
-[architecture]: dev/architecture.md "Architecture"
+[recipes]: recipes/recipes.md "Recipes"
+[recommended-extensions]: recommended-extensions.md "Recommended Extensions"
 [//end]: # "Autogenerated link references"

docs/dev/architecture.md

@@ -1,23 +0,0 @@
----
-tags: architecture
----
-# Architecture
-
-This document aims to provide a quick overview of the Foam architecture!
-
-Foam code and documentation live in the monorepo at [foambubble/foam](https://github.com/foambubble/foam/).
-
-- [/docs](https://github.com/foambubble/foam/tree/master/docs): documentation and [[recipes]].
-- [/packages/foam-core](https://github.com/foambubble/foam/tree/master/packages/foam-core) - Powers the core functionality in Foam across all platforms.
-- [/packages/foam-vscode](https://github.com/foambubble/foam/tree/master/packages/foam-vscode) - The core VSCode plugin.
-
-Exceptions to the monorepo are:
-
-- The starter template at [foambubble/foam-template](https://github.com/foambubble/)
-- All other [[recommended-extensions]] live in their respective GitHub repos.
-- [foam-cli](https://github.com/foambubble/foam-cli) - The Foam CLI tool.
-
-[//begin]: # "Autogenerated link references for markdown compatibility"
-[recipes]: ../recipes/recipes.md "Recipes"
-[recommended-extensions]: ../recommended-extensions.md "Recommended Extensions"
-[//end]: # "Autogenerated link references"

docs/dev/releasing-foam.md

@@ -0,0 +1,27 @@
+# Releasing Foam
+
+1. Get to the latest code
+   - `git checkout master && git fetch && git rebase`
+2. Sanity checks
+   - `yarn reset`
+   - `yarn test`
+3. Update change log 
+   - `./packages/foam-vscode/CHANGELOG.md`
+   - `git add *`
+   - `git commit -m"Preparation for next release"`
+4. Update version
+   - `$ cd packages/foam-vscode`
+   - `foam-vscode$ yarn lerna version <version>` (where `version` is `patch/minor/major`) 
+   - `cd ../..`
+5. Package extension
+   - `$ yarn vscode:package-extension`
+6. Publish extension
+   - `$ yarn vscode:publish-extension`
+7. Update the release notes in GitHub
+   - in GitHub, top right, click on "releases"
+   - select "tags" in top left
+   - select the tag that was just released, click "edit" and copy release information from changelog
+   - publish (no need to attach artifacts)
+8. Annouce on Discord
+
+Steps 1 to 6 should really be replaced by a GitHub action...

docs/features/note-templates.md

@@ -41,12 +41,42 @@ Templates can use all the variables available in [VS Code Snippets](https://code
 
 In addition, you can also use variables provided by Foam:
 
-| Name                 | Description                                                                                                                                             |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `FOAM_SELECTED_TEXT` | Foam will fill it with selected text when creating a new note, if any text is selected. Selected text will be replaced with a wikilink to the new note. |
-| `FOAM_TITLE`         | The title of the note. If used, Foam will prompt you to enter a title for the note.                                                                     |
+| Name                 | Description                                                                                                                                                                                                                 |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `FOAM_SELECTED_TEXT` | Foam will fill it with selected text when creating a new note, if any text is selected. Selected text will be replaced with a wikilink to the new note.                                                                     |
+| `FOAM_TITLE`         | The title of the note. If used, Foam will prompt you to enter a title for the note.                                                                                                                                         |
+| `FOAM_DATE_*`        | `FOAM_DATE_YEAR`, `FOAM_DATE_MONTH`, etc. Foam-specific versions of [VS Code's datetime snippet variables](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_variables). Prefer these versions over VS Code's. |
 
-**Note:** neither the defaulting feature (eg. `${variable:default}`) nor the format feature (eg. `${variable/(.*)/${1:/upcase}/}`) (available to other variables) are available for these Foam-provided variables.
+**Note:** neither the defaulting feature (eg. `${variable:default}`) nor the format feature (eg. `${variable/(.*)/${1:/upcase}/}`) (available to other variables) are available for these Foam-provided variables. See [#693](https://github.com/foambubble/foam/issues/693).
+
+### `FOAM_DATE_*` variables
+
+Foam defines its own set of datetime variables that have a similar behaviour as [VS Code's datetime snippet variables](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_variables).
+
+For example, `FOAM_DATE_YEAR` has the same behaviour as VS Code's `CURRENT_YEAR`, `FOAM_DATE_SECONDS_UNIX` has the same behaviour as `CURRENT_SECONDS_UNIX`, etc.
+
+By default, prefer using the `FOAM_DATE_` versions. The datetime used to compute the values will be the same for both `FOAM_DATE_` and VS Code's variables, with the exception of the creation notes using the daily note template.
+
+#### Relative daily notes
+
+When referring to daily notes, you can use the relative snippets (`/+1d`, `/tomorrow`, etc.). In these cases, the new notes will be created with the daily note template, but the datetime used should be the relative datetime, not the current datetime.
+By using the `FOAM_DATE_` versions of the variables, the correct relative date will populate the variables, instead of the current datetime.
+
+For example, given this daily note template (`.foam/templates/daily-note.md`):
+
+```markdown
+# $FOAM_DATE_YEAR-$FOAM_DATE_MONTH-$FOAM_DATE_DATE
+
+## Here's what I'm going to do today
+
+* Thing 1
+* Thing 2
+```
+
+When the `/tomorrow` snippet is used, `FOAM_DATE_` variables will be populated with tomorrow's date, as expected.
+If instead you were to use the VS Code versions of these variables, they would be populated with today's date, not tomorrow's, causing unexpected behaviour.
+
+When creating notes in any other scenario, the `FOAM_DATE_` values are computed using the same datetime as the VS Code ones, so the `FOAM_DATE_` versions can be used in all scenarios by default.
 
 ## Metadata
 

docs/index.md

@@ -72,6 +72,8 @@ These instructions assume you have a GitHub account, and you have Visual Studio
 
 After setting up the repository, open `.vscode/settings.json` and edit, add or remove any settings you'd like for your Foam workspace.
 
+* *If using a [multi-root workspace](https://code.visualstudio.com/docs/editor/multi-root-workspaces) as noted above, make sure that your **Foam** directory is first in the list. There are some settings that will need to be migrated from `.vscode/settings.json` to your `.code-workspace` file.*
+
 To learn more about how to use **Foam**, read the [[recipes]].
 
 Getting stuck in the setup? Read the [[frequently-asked-questions]].
@@ -210,6 +212,14 @@ If that sounds like something you're interested in, I'd love to have you along o
     <td align="center"><a href="https://github.com/theowenyoung"><img src="https://avatars.githubusercontent.com/u/62473795?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Owen Young</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=theowenyoung" title="Documentation">📖</a> <a href="#content-theowenyoung" title="Content">🖋</a></td>
     <td align="center"><a href="http://www.prashu.com"><img src="https://avatars.githubusercontent.com/u/476729?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Prashanth Subrahmanyam</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=ksprashu" title="Documentation">📖</a></td>
     <td align="center"><a href="https://github.com/JonasSprenger"><img src="https://avatars.githubusercontent.com/u/25108895?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Jonas SPRENGER</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=JonasSprenger" title="Code">💻</a></td>
+    <td align="center"><a href="https://github.com/Laptop765"><img src="https://avatars.githubusercontent.com/u/1468359?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Paul</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=Laptop765" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://bandism.net/"><img src="https://avatars.githubusercontent.com/u/22633385?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Ikko Ashimine</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=eltociear" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/memeplex"><img src="https://avatars.githubusercontent.com/u/2845433?v=4?s=60" width="60px;" alt=""/><br /><sub><b>memeplex</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=memeplex" title="Code">💻</a></td>
+  </tr>
+  <tr>
+    <td align="center"><a href="https://github.com/AndreiD049"><img src="https://avatars.githubusercontent.com/u/52671223?v=4?s=60" width="60px;" alt=""/><br /><sub><b>AndreiD049</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=AndreiD049" title="Code">💻</a></td>
+    <td align="center"><a href="https://github.com/iam-yan"><img src="https://avatars.githubusercontent.com/u/48427014?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Yan</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=iam-yan" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://WikiEducator.org/User:JimTittsler"><img src="https://avatars.githubusercontent.com/u/180326?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Jim Tittsler</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=jimt" title="Documentation">📖</a></td>
   </tr>
 </table>
 

docs/proposals/wikilinks-in-foam.md

@@ -0,0 +1,93 @@
+# Wikilinks in Foam
+
+Foam supports standard wikilinks in the format `[[wikilink]]`.
+
+Wikilinks can refer to any note or attachment in the repo: `[[note.md]]`, `[[doc.pdf]]`, `[[image.jpg]]`.
+
+The usual wikilink syntax without extension refers to notes: `[[wikilink]]` and `[[wikilink.md]]` are equivalent.
+
+The goal of wikilinks is to uniquely identify a file in a repo, no matter in which directory it lives.
+
+Sometimes in a repo you can have files with the same name in different directories.
+Foam allows you to identify those files using the minimum effort needed to disambiguate them.
+
+This is achieved by adding as many directories above the file needed to uniquely identify the link, e.g. `[[house/todo]]`.
+
+See below for more details.
+
+## Goals for wikilinks in Foam
+
+Wikilinks in Foam are meant to satisfy the following:
+- make it easy for users to identify a resource
+- make it interoperable with other similar note taking systems (Obsidian, Dendron, ...)
+- be easy to get started with, but satisfy growing needs
+
+## Types of wikilinks supported in Foam
+
+Foam supports two types of keys inside a wikilink: a **path** reference and an **identifier** reference:
+
+- `[[./file]]` and `[[../to/another/file]]` are **path** links to a resource, relative _from the source_
+- `[[/path/to/file]]` is a **path** link to a resource, relative _from the repo root_
+- `[[file]]` is an **identifier** of a resource (based on the filename)
+- `[[path/to/file]]` is an **identifier** of a resource (based on the path), the same is true for `[[to/file]]`
+
+It's important to note that sometimes identifier keys can't uniquely locale a resource.
+
+A more concrete example will help:
+
+```
+/
+  projects/
+    house/
+      todo.md
+    buy-car/
+      todo.md
+      cars.md
+  work/
+    todo.md
+    notes.md
+```
+
+In the above repo:
+
+- `[[cars]]` is a unique identifier of a resource - it can be used anywhere in the repo
+- `[[todo]]` is an non-unique identifier as it can refer to multiple resources
+- `[[house/todo]]` is a unique identifier of a resource - it can be used anywhere in the repo
+- `[[projects/house/todo]]` is a unique identifier of a resource - it can be used anywhere in the repo
+- `[[/projects/house/todo]]` is a path reference to a resource
+- `[[./todo]]` is a path reference to a resource (e.g. from `/projects/buy-car/cars.md`)
+
+Basically we could say as a rule:
+
+- if the link starts with `/` or `.` we consider it a **path** reference, in the first case from the repo root, otherwise from the source note
+- if a link doesn't start with `/` or `.` it is an **identifier**
+  - generally speaking we use the shortest identifier available to identify a resource, **but all are valid**
+    - `[[projects/buy-car/cars]]`, `[[buy-car/cars]]`, `[[cars]]` are all unique identifier to the same resource, and are all valid in a document
+    - the same can be said for `[[projects/house/todo]]` and `[[house/todo]]` - but not for `[[todo]]`, because it can refer to more than one resource
+
+## Compatibility with other apps
+
+| Scenario                    | Obsidian                        | Foam                            |
+| --------------------------- | ------------------------------- | ------------------------------- |
+| 1 `[[notes]]`               | ✔ unique identifier in repo     | ✔ unique identifier in repo     |
+| 2 `[[/work/notes]]`         | ✔ valid path from repo root     | ✔ valid path from repo root     |
+| 3 `[[work/notes]]`          | ✔ valid path from repo root     | ✔ valid identifier in repo      |
+| 4 `[[project/house/todo]]`  | ✔ valid path from repo root     | ✔ valid unique identifier       |
+| 5 `[[/project/house/todo]]` | ✔ valid path from repo root     | ✔ valid path from repo root     |
+| 6 `[[house/todo]]`          | ✔ valid unique identifier       | ✔ valid unique identifier       |
+| 7 `[[todo]]`                | ✘ ambiguous identifier          | ✘ ambiguous identifier          |
+| 8 `[[/house/todo]]`         | ✘ incorrect path from repo root | ✘ incorrect path from repo root |
+
+## Non-unique identifiers
+
+We can't prevent non-unique identifiers from occurring in Foam (first and foremost because a file could be edited with another editor) but we can flag them. 
+
+Therefore Foam follows the following strategy instead:
+
+1. there is a clear resolution mechanism (alphabetic) so that if nothing changes a non-unique identifier will always return the same note. Resolution has to be deterministic
+2. a diagnostic entry (warning or error) is showed to the user for non-unique identifiers, so she knows that she's using a "risky" identifier
+   1. The quick resolution for this item will show the available unique identifiers matching the non-unique one
+
+## Thanks 
+
+Thanks to [@memplex](https://github.com/memeplex) for helping with the thinking around this proposal.

docs/recipes/write-your-notes-in-github-gist.md

@@ -34,7 +34,7 @@ Once you've opened/created the Foam repository, it will appear in the `Repositor
 
 ## Editing your workspace
 
-When you create or open a page, you can edit the markdown content as usual, as well as [paste images](https://github.com/vsls-contrib/gistpad#pasting-images-1), and create [`[[links]]` to other pages](https://github.com/vsls-contrib/gistpad#links). When you type `[[`, you'll recieve auto-completion for the existing pages in your workspace, and you can also automatically create new pages by simply creating a link to it.
+When you create or open a page, you can edit the markdown content as usual, as well as [paste images](https://github.com/vsls-contrib/gistpad#pasting-images-1), and create [`[[links]]` to other pages](https://github.com/vsls-contrib/gistpad#links). When you type `[[`, you'll receive auto-completion for the existing pages in your workspace, and you can also automatically create new pages by simply creating a link to it.
 
 Since you're using the Visual Studio Code markdown editor, you can benefit from all of the rich language services (e.g. syntax highlighting, header collapsing), as well as the extension ecosystem (e.g. [Emojisense](https://marketplace.visualstudio.com/items?itemName=bierner.emojisense)).
 

docs/wikilinks.md

@@ -3,7 +3,6 @@
 Foam enables you to Link pages together using `[[file-name]]` annotations (i.e. `[[MediaWiki]]` links).
 
 - Type `[[` and start typing a file name for autocompletion.
-  - Note that your file names should be in `lower-dash-case.md`, and your wikilinks should reference file names exactly: `[[lower-dash-case]]`, not `[[Lower Dash Case]]`.
   - See [[link-formatting-and-autocompletion]] for more information, and how to setup your link autocompletions to make this easier.
 - `Cmd` + `Click` ( `Ctrl` + `Click` on Windows ) on file name to navigate to file (`F12` also works while your cursor is on the file name)
 - `Cmd` + `Click` ( `Ctrl` + `Click` on Windows ) on non-existent file to create that file in the workspace.
@@ -11,6 +10,10 @@ Foam enables you to Link pages together using `[[file-name]]` annotations (i.e.
 
 > If the `F12` shortcut feels unnatural you can rebind it at File > Preferences > Keyboard Shortcuts by searching for `editor.action.revealDefinition`.
 
+## Support for sections
+
+Foam supports autocompletion, navigation, embedding and diagnostics for note sections. Just use the standard wiki syntax of `[[resource#Section Title]]`.
+
 ## Markdown compatibility
 
 The [Foam for VSCode](https://marketplace.visualstudio.com/items?itemName=foam.foam-vscode) extension automatically generates [[link-reference-definitions]] at the bottom of the file to make wikilinks compatible with Markdown tools and parsers.

lerna.json

@@ -4,5 +4,5 @@
   ],
   "npmClient": "yarn",
   "useWorkspaces": true,
-  "version": "0.15.0"
+  "version": "0.17.1"
 }

package.json

@@ -9,10 +9,6 @@
     "packages/*"
   ],
   "scripts": {
-    "start:vscode": "yarn workspace foam-vscode vscode:start-debugging",
-    "build:core": "yarn workspace foam-core build",
-    "watch:core": "yarn workspace foam-core start",
-    "test:core": "yarn workspace foam-core test",
     "vscode:package-extension": "yarn workspace foam-vscode package-extension",
     "vscode:install-extension": "yarn workspace foam-vscode install-extension",
     "vscode:publish-extension": "yarn workspace foam-vscode publish-extension",

packages/foam-core/.babelrc.js

@@ -1,3 +0,0 @@
-module.exports = {
-  plugins: [['@babel/plugin-transform-runtime', { helpers: false }]],
-};

packages/foam-core/README.md

@@ -1,21 +0,0 @@
-# Foam Core
-
-This module contains the core functions, model, and API of Foam.
-It is used by its clients to integrate Foam in various use cases, from VsCode extension, to CLI, to CI integrations.
-
-## Local Development
-
-Below is a list of commands you will probably find useful.
-
-### `yarn watch`
-
-Runs the project in development/watch mode. Your project will be rebuilt upon changes.
-
-### `yarn build`
-
-Bundles the package to the `dist` folder. The package is optimized and bundled with Rollup into multiple formats (CommonJS, UMD, and ES Module).
-
-### `yarn test`
-
-Runs the test watcher (Jest) in an interactive mode.
-By default, runs tests related to files changed since the last commit.

packages/foam-core/package.json

@@ -1,49 +0,0 @@
-{
-  "name": "foam-core",
-  "repository": "https://github.com/foambubble/foam",
-  "version": "0.15.0",
-  "license": "MIT",
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "clean": "rimraf dist",
-    "build": "tsdx build --tsconfig ./tsconfig.build.json",
-    "test": "tsdx test",
-    "lint": "tsdx lint src test",
-    "watch": "tsdx watch",
-    "prepare": "tsdx build --tsconfig ./tsconfig.build.json"
-  },
-  "devDependencies": {
-    "@babel/core": "^7.10.4",
-    "@babel/plugin-transform-runtime": "^7.10.4",
-    "@babel/preset-env": "^7.10.4",
-    "@babel/preset-typescript": "^7.10.4",
-    "@types/github-slugger": "^1.3.0",
-    "@types/lodash": "^4.14.157",
-    "@types/micromatch": "^4.0.1",
-    "@types/picomatch": "^2.2.1",
-    "husky": "^4.2.5",
-    "tsdx": "^0.13.2",
-    "tslib": "^2.0.0",
-    "typescript": "^3.9.5"
-  },
-  "dependencies": {
-    "detect-newline": "^3.1.0",
-    "fast-array-diff": "^1.0.1",
-    "github-slugger": "^1.3.0",
-    "glob": "^7.1.6",
-    "lodash": "^4.17.21",
-    "micromatch": "^4.0.2",
-    "remark-frontmatter": "^2.0.0",
-    "remark-parse": "^8.0.2",
-    "remark-wiki-link": "^0.0.4",
-    "replace-ext": "^2.0.0",
-    "title-case": "^3.0.2",
-    "unified": "^9.0.0",
-    "unist-util-visit": "^2.0.2",
-    "yaml": "^1.10.0"
-  },
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts"
-}

packages/foam-core/src/config.ts

@@ -1,75 +0,0 @@
-import { readFileSync } from 'fs';
-import { merge } from 'lodash';
-import { Logger } from './utils/log';
-import { URI } from './model/uri';
-
-export interface FoamConfig {
-  workspaceFolders: URI[];
-  includeGlobs: string[];
-  ignoreGlobs: string[];
-  get<T>(path: string): T | undefined;
-  get<T>(path: string, defaultValue: T): T;
-}
-
-const DEFAULT_INCLUDES = ['**/*'];
-
-const DEFAULT_IGNORES = ['**/node_modules/**'];
-
-export const createConfigFromObject = (
-  workspaceFolders: URI[],
-  include: string[],
-  ignore: string[],
-  settings: any
-) => {
-  const config: FoamConfig = {
-    workspaceFolders: workspaceFolders,
-    includeGlobs: include,
-    ignoreGlobs: ignore,
-    get: <T>(path: string, defaultValue?: T) => {
-      const tokens = path.split('.');
-      const value = tokens.reduce((acc, t) => acc?.[t], settings);
-      return value ?? defaultValue;
-    },
-  };
-  return config;
-};
-
-export const createConfigFromFolders = (
-  workspaceFolders: URI[] | URI,
-  options: {
-    include?: string[];
-    ignore?: string[];
-  } = {}
-): FoamConfig => {
-  if (!Array.isArray(workspaceFolders)) {
-    workspaceFolders = [workspaceFolders];
-  }
-  const workspaceConfig: any = workspaceFolders.reduce(
-    (acc, f) => merge(acc, parseConfig(URI.joinPath(f, 'config.json'))),
-    {}
-  );
-  // For security reasons local plugins can only be
-  // activated via user config
-  if ('experimental' in workspaceConfig) {
-    delete workspaceConfig['experimental']['localPlugins'];
-  }
-
-  const userConfig = parseConfig(URI.file(`~/.foam/config.json`));
-
-  const settings = merge(workspaceConfig, userConfig);
-
-  return createConfigFromObject(
-    workspaceFolders,
-    options.include ?? DEFAULT_INCLUDES,
-    options.ignore ?? DEFAULT_IGNORES,
-    settings
-  );
-};
-
-const parseConfig = (path: URI) => {
-  try {
-    return JSON.parse(readFileSync(URI.toFsPath(path), 'utf8'));
-  } catch {
-    Logger.debug('Could not read configuration from ' + URI.toString(path));
-  }
-};

packages/foam-core/src/index.ts

@@ -1,64 +0,0 @@
-import {
-  Resource,
-  ResourceLink,
-  NoteLinkDefinition,
-  ResourceParser,
-  Tag,
-} from './model/note';
-import { FoamConfig } from './config';
-import {
-  IDataStore,
-  FileDataStore,
-  Matcher,
-  IMatcher,
-} from './services/datastore';
-import { ILogger } from './utils/log';
-import { IDisposable, isDisposable } from './common/lifecycle';
-import { FoamWorkspace } from './model/workspace';
-import { FoamGraph } from '../src/model/graph';
-import { URI } from './model/uri';
-import { FoamTags } from '../src/model/tags';
-
-export { Position } from './model/position';
-export { Range } from './model/range';
-export { IDataStore, FileDataStore, Matcher, IMatcher };
-export { ILogger };
-export { LogLevel, LogLevelThreshold, Logger, BaseLogger } from './utils/log';
-export { Event, Emitter } from './common/event';
-export { FoamConfig };
-export { ResourceProvider } from './model/provider';
-export { IDisposable, isDisposable };
-
-export {
-  createMarkdownReferences,
-  stringifyMarkdownLinkReferenceDefinition,
-  createMarkdownParser,
-  MarkdownResourceProvider,
-} from './markdown-provider';
-
-export {
-  TextEdit,
-  generateHeading,
-  generateLinkReferences,
-  getKebabCaseFileName,
-  LINK_REFERENCE_DEFINITION_HEADER,
-  LINK_REFERENCE_DEFINITION_FOOTER,
-} from './janitor';
-
-export { applyTextEdit } from './janitor/apply-text-edit';
-
-export { createConfigFromFolders } from './config';
-
-export { Foam, Services, bootstrap } from './model/foam';
-
-export {
-  Resource,
-  ResourceLink,
-  URI,
-  Tag,
-  FoamWorkspace,
-  FoamGraph,
-  FoamTags,
-  NoteLinkDefinition,
-  ResourceParser,
-};

packages/foam-core/src/model/workspace.ts

@@ -1,178 +0,0 @@
-import * as path from 'path';
-import { Resource, ResourceLink } from './note';
-import { URI } from './uri';
-import { isSome, isNone } from '../utils';
-import { Emitter } from '../common/event';
-import { IDisposable } from '../index';
-import { ResourceProvider } from './provider';
-
-export function getReferenceType(
-  reference: URI | string
-): 'uri' | 'absolute-path' | 'relative-path' | 'key' {
-  if (URI.isUri(reference)) {
-    return 'uri';
-  }
-  const isPath = reference.split('/').length > 1;
-  if (!isPath) {
-    return 'key';
-  }
-  const isAbsPath = isPath && reference.startsWith('/');
-  return isAbsPath ? 'absolute-path' : 'relative-path';
-}
-
-const pathToResourceId = (pathValue: string) => {
-  const { ext } = path.parse(pathValue);
-  return ext.length > 0 ? pathValue : pathValue + '.md';
-};
-const uriToResourceId = (uri: URI) => pathToResourceId(uri.path);
-
-const pathToResourceName = (pathValue: string) =>
-  path.parse(pathValue).name.toLowerCase();
-export const uriToResourceName = (uri: URI) => pathToResourceName(uri.path);
-
-export class FoamWorkspace implements IDisposable {
-  private onDidAddEmitter = new Emitter<Resource>();
-  private onDidUpdateEmitter = new Emitter<{ old: Resource; new: Resource }>();
-  private onDidDeleteEmitter = new Emitter<Resource>();
-  onDidAdd = this.onDidAddEmitter.event;
-  onDidUpdate = this.onDidUpdateEmitter.event;
-  onDidDelete = this.onDidDeleteEmitter.event;
-
-  private providers: ResourceProvider[] = [];
-
-  /**
-   * Resources by key / slug
-   */
-  private resourcesByName: Map<string, string[]> = new Map();
-  /**
-   * Resources by URI
-   */
-  private resources: Map<string, Resource> = new Map();
-
-  registerProvider(provider: ResourceProvider) {
-    this.providers.push(provider);
-    return provider.init(this);
-  }
-
-  set(resource: Resource) {
-    const id = uriToResourceId(resource.uri);
-    const old = this.find(resource.uri);
-    const name = uriToResourceName(resource.uri);
-    this.resources.set(id, resource);
-    if (!this.resourcesByName.has(name)) {
-      this.resourcesByName.set(name, []);
-    }
-    this.resourcesByName.get(name)?.push(id);
-    isSome(old)
-      ? this.onDidUpdateEmitter.fire({ old: old, new: resource })
-      : this.onDidAddEmitter.fire(resource);
-    return this;
-  }
-
-  delete(uri: URI) {
-    const id = uriToResourceId(uri);
-    const deleted = this.resources.get(id);
-    this.resources.delete(id);
-
-    const name = uriToResourceName(uri);
-    this.resourcesByName.set(
-      name,
-      this.resourcesByName.get(name)?.filter(resId => resId !== id) ?? []
-    );
-    if (this.resourcesByName.get(name)?.length === 0) {
-      this.resourcesByName.delete(name);
-    }
-
-    isSome(deleted) && this.onDidDeleteEmitter.fire(deleted);
-    return deleted ?? null;
-  }
-
-  public exists(uri: URI): boolean {
-    return (
-      !URI.isPlaceholder(uri) &&
-      isSome(this.resources.get(uriToResourceId(uri)))
-    );
-  }
-
-  public list(): Resource[] {
-    return Array.from(this.resources.values());
-  }
-
-  public get(uri: URI): Resource {
-    const note = this.find(uri);
-    if (isSome(note)) {
-      return note;
-    } else {
-      throw new Error('Resource not found: ' + uri.path);
-    }
-  }
-
-  public find(resourceId: URI | string, reference?: URI): Resource | null {
-    const refType = getReferenceType(resourceId);
-    switch (refType) {
-      case 'uri':
-        const uri = resourceId as URI;
-        return this.exists(uri)
-          ? this.resources.get(uriToResourceId(uri)) ?? null
-          : null;
-
-      case 'key':
-        const name = pathToResourceName(resourceId as string);
-        let paths = this.resourcesByName.get(name);
-
-        if (isNone(paths) || paths.length === 0) {
-          paths = this.resourcesByName.get(resourceId as string);
-        }
-
-        if (isNone(paths) || paths.length === 0) {
-          return null;
-        }
-        // prettier-ignore
-        const sortedPaths = paths.length === 1
-          ? paths
-          : paths.sort((a, b) => a.localeCompare(b));
-
-        return this.resources.get(sortedPaths[0]) ?? null;
-
-      case 'absolute-path':
-        const resourceUri = URI.file(resourceId as string);
-        return this.resources.get(uriToResourceId(resourceUri)) ?? null;
-
-      case 'relative-path':
-        if (isNone(reference)) {
-          return null;
-        }
-        const relativePath = resourceId as string;
-        const targetUri = URI.computeRelativeURI(reference, relativePath);
-        return this.resources.get(uriToResourceId(targetUri)) ?? null;
-
-      default:
-        throw new Error('Unexpected reference type: ' + refType);
-    }
-  }
-
-  public resolveLink(resource: Resource, link: ResourceLink): URI {
-    // TODO add tests
-    const provider = this.providers.find(p => p.supports(resource.uri));
-    return (
-      provider?.resolveLink(this, resource, link) ??
-      URI.placeholder(link.target)
-    );
-  }
-
-  public read(uri: URI): Promise<string | null> {
-    const provider = this.providers.find(p => p.supports(uri));
-    return provider?.read(uri) ?? Promise.resolve(null);
-  }
-
-  public readAsMarkdown(uri: URI): Promise<string | null> {
-    const provider = this.providers.find(p => p.supports(uri));
-    return provider?.readAsMarkdown(uri) ?? Promise.resolve(null);
-  }
-
-  public dispose(): void {
-    this.onDidAddEmitter.dispose();
-    this.onDidDeleteEmitter.dispose();
-    this.onDidUpdateEmitter.dispose();
-  }
-}

packages/foam-core/test/config.test.ts

@@ -1,44 +0,0 @@
-import { createConfigFromFolders } from '../src/config';
-import { Logger } from '../src/utils/log';
-import { URI } from '../src/model/uri';
-
-Logger.setLevel('error');
-
-const testFolder = URI.joinPath(URI.file(__dirname), 'test-config');
-
-describe('Foam configuration', () => {
-  it('can read settings from config.json', () => {
-    const config = createConfigFromFolders([
-      URI.joinPath(testFolder, 'folder1'),
-    ]);
-    expect(config.get('feature1.setting1.value')).toBeTruthy();
-    expect(config.get('feature2.value')).toEqual(12);
-
-    const section = config.get<{ value: boolean }>('feature1.setting1');
-    expect(section!.value).toBeTruthy();
-  });
-
-  it('can merge settings from multiple foam folders', () => {
-    const config = createConfigFromFolders([
-      URI.joinPath(testFolder, 'folder1'),
-      URI.joinPath(testFolder, 'folder2'),
-    ]);
-
-    // override value
-    expect(config.get('feature1.setting1.value')).toBe(false);
-    // this was not overridden
-    expect(config.get('feature1.setting1.extraValue')).toEqual('go foam');
-    // new value from second config file
-    expect(config.get('feature1.setting1.value2')).toBe('hello');
-
-    // this whole section doesn't exist in second file
-    expect(config.get('feature2.value')).toEqual(12);
-  });
-
-  it('cannot activate local plugins from workspace config', () => {
-    const config = createConfigFromFolders([
-      URI.joinPath(testFolder, 'enable-plugins'),
-    ]);
-    expect(config.get('experimental.localPlugins.enabled')).toBeUndefined();
-  });
-});

packages/foam-core/test/core.test.ts

@@ -1,99 +0,0 @@
-import path from 'path';
-import { FoamWorkspace } from '../src';
-import { NoteLinkDefinition, Resource } from '../src/model/note';
-import { IDataStore, Matcher } from '../src/services/datastore';
-import { MarkdownResourceProvider } from '../src/markdown-provider';
-import { Range } from '../src/model/range';
-import { URI } from '../src/model/uri';
-import { Logger } from '../src/utils/log';
-
-Logger.setLevel('error');
-
-const position = Range.create(0, 0, 0, 100);
-
-const documentStart = position.start;
-const documentEnd = position.end;
-const eol = '\n';
-
-/**
- * Turns a string into a URI
- * The goal of this function is to make sure we are consistent in the
- * way we generate URIs (and therefore IDs) across the tests
- */
-export const strToUri = URI.file;
-
-export const noOpDataStore = (): IDataStore => ({
-  read: _ => Promise.resolve(''),
-  list: _ => Promise.resolve([]),
-});
-
-export const createTestWorkspace = () => {
-  const workspace = new FoamWorkspace();
-  const matcher = new Matcher([URI.file('/')], ['**/*']);
-  const provider = new MarkdownResourceProvider(
-    matcher,
-    undefined,
-    undefined,
-    noOpDataStore()
-  );
-  workspace.registerProvider(provider);
-  return workspace;
-};
-
-export const createTestNote = (params: {
-  uri: string;
-  title?: string;
-  definitions?: NoteLinkDefinition[];
-  links?: Array<{ slug: string } | { to: string }>;
-  text?: string;
-  root?: URI;
-  tags?: string[];
-}): Resource => {
-  const root = params.root ?? URI.file('/');
-  return {
-    uri: URI.resolve(params.uri, root),
-    type: 'note',
-    properties: {},
-    title: params.title ?? path.parse(strToUri(params.uri).path).base,
-    definitions: params.definitions ?? [],
-    tags:
-      params.tags?.map(t => ({
-        label: t,
-        range: Range.create(0, 0, 0, 0),
-      })) ?? [],
-    links: params.links
-      ? params.links.map((link, index) => {
-          const range = Range.create(
-            position.start.line + index,
-            position.start.character,
-            position.start.line + index,
-            position.end.character
-          );
-          return 'slug' in link
-            ? {
-                type: 'wikilink',
-                target: link.slug,
-                label: link.slug,
-                range: range,
-                rawText: 'link text',
-              }
-            : {
-                type: 'link',
-                target: link.to,
-                label: 'link text',
-                range: range,
-              };
-        })
-      : [],
-    source: {
-      eol: eol,
-      end: documentEnd,
-      contentStart: documentStart,
-      text: params.text ?? '',
-    },
-  };
-};
-
-describe('Test utils', () => {
-  it('are happy', () => {});
-});

packages/foam-core/test/uri.test.ts

@@ -1,51 +0,0 @@
-import { Logger } from '../src';
-import { URI } from '../src/model/uri';
-import { uriToSlug } from '../src/utils/slug';
-
-Logger.setLevel('error');
-
-describe('Foam URIs', () => {
-  describe('URI parsing', () => {
-    const base = URI.file('/path/to/file.md');
-    test.each([
-      ['https://www.google.com', URI.parse('https://www.google.com')],
-      ['/path/to/a/file.md', URI.file('/path/to/a/file.md')],
-      ['../relative/file.md', URI.file('/path/relative/file.md')],
-      ['#section', URI.create({ ...base, fragment: 'section' })],
-      [
-        '../relative/file.md#section',
-        URI.parse('file:/path/relative/file.md#section'),
-      ],
-    ])('URI Parsing (%s) - %s', (input, exp) => {
-      const result = URI.resolve(input, base);
-      expect(result.scheme).toEqual(exp.scheme);
-      expect(result.authority).toEqual(exp.authority);
-      expect(result.path).toEqual(exp.path);
-      expect(result.query).toEqual(exp.query);
-      expect(result.fragment).toEqual(exp.fragment);
-    });
-  });
-  it('supports various cases', () => {
-    expect(uriToSlug(URI.file('/this/is/a/path.md'))).toEqual('path');
-    expect(uriToSlug(URI.file('../a/relative/path.md'))).toEqual('path');
-    expect(uriToSlug(URI.file('another/relative/path.md'))).toEqual('path');
-    expect(uriToSlug(URI.file('no-directory.markdown'))).toEqual(
-      'no-directory'
-    );
-    expect(uriToSlug(URI.file('many.dots.name.markdown'))).toEqual(
-      'manydotsname'
-    );
-  });
-
-  it('computes a relative uri using a slug', () => {
-    expect(
-      URI.computeRelativeURI(URI.file('/my/file.md'), '../hello.md')
-    ).toEqual(URI.file('/hello.md'));
-    expect(URI.computeRelativeURI(URI.file('/my/file.md'), '../hello')).toEqual(
-      URI.file('/hello.md')
-    );
-    expect(
-      URI.computeRelativeURI(URI.file('/my/file.markdown'), '../hello')
-    ).toEqual(URI.file('/hello.markdown'));
-  });
-});

packages/foam-core/tsconfig.build.json

@@ -1,6 +0,0 @@
-{
-  "extends": "./tsconfig.json",
-  "compilerOptions": {
-    "module": "ESNext"
-  }
-}

packages/foam-core/tsconfig.json

@@ -1,29 +0,0 @@
-{
-  "extends": "../../tsconfig.base.json",
-  "compilerOptions": {
-    "baseUrl": "src",
-    "composite": true,
-    "esModuleInterop": true,
-    "importHelpers": true,
-    "downlevelIteration": true,
-    // commonjs module format is used so that the incremental
-    // tsc build-mode ran during development can replace individual
-    // files (as opposed to generate the .cjs.development.js bundle.
-    //
-    // this is overridden in tsconfig.build.json for distribution
-    "module": "commonjs",
-
-    "moduleResolution": "node",
-    "outDir": "dist",
-    "rootDir": "./src",
-    "sourceMap": true,
-    "strict": true,
-    "lib": [
-      "ES2019", "es2020.string"
-    ]
-  },
-  "include": [
-    "src",
-    "types"
-  ]
-}

packages/foam-vscode/CHANGELOG.md

@@ -4,6 +4,116 @@ All notable changes to the "foam-vscode" extension will be documented in this fi
 
 Check [Keep a Changelog](http://keepachangelog.com/) for recommendations on how to structure this file.
 
+## [0.17.1] - 2021-12-16
+
+Fixes and Improvements:
+- Decorate markdown files only (#857)
+- Fix template placeholders issue (#859)
+- Improved replacement range for link completion
+
+Internal:
+- Major URI/path handling refactoring (#858 - thanks @memeplex)
+
+## [0.17.0] - 2021-12-08
+
+Features:
+
+- Added first class support for sections (#856)
+  - Sections can be referred to in wikilinks
+  - Sections can be embedded
+  - Autocompletion for sections
+  - Diagnostic for sections
+  - Embed sections
+
+## [0.16.1] - 2021-11-30
+
+Fixes and Improvements:
+
+- Fixed diagnostic bug triggered when file had same suffix (#851)
+
+## [0.16.0] - 2021-11-24
+
+Features:
+
+- Added support for unique wikilink identifiers (#841)
+  - This change allows files that have the same name to be uniquely referenced as wikilinks
+  - BREAKING CHANGE: wikilinks to attachments must now include the extension
+- Added diagnostics for ambiguous wikilinks, with quick fixes available (#844)
+- Added support for unique wikilinks in autocompletion (#845)
+
+## [0.15.9] - 2021-11-23
+
+Fixes and Improvements:
+
+- Fixed filepath retrieval when creating note from template (#843)
+
+## [0.15.8] - 2021-11-22
+
+Fixes and Improvements:
+
+- Re-enable link navigation for wikilinks (#840)
+
+## [0.15.7] - 2021-11-21
+
+Fixes and Improvements:
+
+- Fixed template listing (#831)
+- Fixed note creation from template (#834)
+
+## [0.15.6] - 2021-11-18
+
+Fixes and Improvements:
+
+- Link Reference Generation is now OFF by default
+- Fixed preview navigation (#830)
+
+
+## [0.15.5] - 2021-11-15
+
+Fixes and Improvements:
+
+- Major improvement in navigation. Use link definitions and link references (#821)
+- Fixed bug showing in hover reference the same more than once when it had multiple links to another (#822)
+
+Internal:
+
+- Foam URI refactoring (#820)
+- Template service refactoring (#825)
+
+## [0.15.4] - 2021-11-09
+
+Fixes and Improvements:
+
+- Detached Foam URI from VS Code URI. This should improve several path related issues in Windows. Given how core this change is, the release is just about this refactoring to easily detect possible side effects.
+
+## [0.15.3] - 2021-11-08
+
+Fixes and Improvements:
+
+- Avoid delaying decorations on editor switch (#811 - thanks @memeplex)
+- Fix preview issue when embedding a note and using reference definitions (#808 - thanks @pderaaij)
+
+## [0.15.2] - 2021-10-27
+
+Features:
+
+- Added `FOAM_DATE_*` template variables (#781)
+
+Fixes and Improvements:
+
+- Dataviz: apply note type color to filter item label
+- Dataviz: optimized rendering of graph to reduce load on CPU (#795)
+- Preview: improved tag highlight in preview (#785 - thanks @pderaaij)
+- Better handling of link reference definition (#786 - thanks @pderaaij)
+- Link decorations are now enabled by default (can be turned off in settings)
+
+## [0.15.1] - 2021-10-21
+
+Fixes and Improvements:
+
+- Improved filtering controls for graph (#782)
+- Link Hover: Include other connected notes to link target
+
 ## [0.15.0] - 2021-10-04
 
 Features:
@@ -18,7 +128,7 @@ Fixes and Improvements:
 
 ## [0.14.2] - 2021-07-24
 
-Features: 
+Features:
 
 - Autocompletion for tags (#708 - thanks @pderaaij)
 - Use templates for new note created from wikilink (#712 - thanks @movermeyer)
@@ -35,7 +145,7 @@ Fixes and Improvements:
 
 ## [0.14.0] - 2021-07-13
 
-Features: 
+Features:
 
 - Create new note from selection (#666 - thanks @pderaaij)
 - Use templates for daily notes (#700 - thanks @movermeyer)
@@ -63,9 +173,9 @@ Fixes and Improvements:
 
 - Fixed #667, incorrect resolution of foam-core library
 
-Internal: 
+Internal:
 
-- BREAKING CHANGE: Removed Foam local plugins 
+- BREAKING CHANGE: Removed Foam local plugins
   If you were previously using the alpha feature of Foam local plugins you will soon be able to migrate the functionality to the V1 API
 
 ## [0.13.6] - 2021-06-05

packages/foam-vscode/README.md

@@ -5,15 +5,127 @@
 [![Installs](https://img.shields.io/visual-studio-marketplace/i/foam.foam-vscode)](https://marketplace.visualstudio.com/items?itemName=foam.foam-vscode)
 [![Ratings](https://img.shields.io/visual-studio-marketplace/r/foam.foam-vscode)](https://marketplace.visualstudio.com/items?itemName=foam.foam-vscode)
 
-> ⚠️ This is an early stage software. Use at your own peril.
 > You can join the Foam Community on the [Foam Discord](https://foambubble.github.io/join-discord/e)
 
-[Foam](https://foambubble.github.io/foam) is a note-taking tool that lives within VsCode, which means you can pair it with your favorite extensions for a great editing experience.
+[Foam](https://foambubble.github.io/foam) is a note-taking tool that lives within VS Code, which means you can pair it with your favorite extensions for a great editing experience.
 
 Foam is open source, and allows you to create a local first, markdown based, personal knowledge base. You can also use it to publish your notes.
 
 Foam is also meant to be extensible, so you can integrate with its internals to customize your knowledge base.
 
+## Features
+
+### Graph Visualization
+
+See how your notes are connected via a [graph](https://foambubble.github.io/foam/features/graph-visualisation) with the `Foam: Show Graph` command.
+
+![Graph Visualization](./assets/screenshots/feature-show-graph.gif)
+
+### Link Autocompletion
+
+Foam helps you create the connections between your notes, and your placeholders as well.
+
+![Link Autocompletion](./assets/screenshots/feature-link-autocompletion.gif)
+
+### Unique identifiers across directories
+
+Foam supports files with the same name in multiple directories.
+It will use the minimum identifier required, and even report and help you fix existing ambiguous wikilinks.
+
+![Unique identifier autocompletion](./assets/screenshots/feature-unique-wikilink-completion.gif)
+
+![Wikilink diagnostic](./assets/screenshots/feature-wikilink-diagnostics.gif)
+
+### Link Preview and Navigation
+
+![Link Preview and Navigation](./assets/screenshots/feature-navigation.gif)
+
+### Go to definition, Peek References
+
+See where a note is being referenced in your knowledge base.
+
+![Go to Definition, Peek References](./assets/screenshots/feature-definition-references.gif)
+
+### Navigation in Preview
+
+Navigate your rendered notes in the VS Code preview panel.
+
+![Navigation in Preview](./assets/screenshots/feature-preview-navigation.gif)
+
+### Note embed
+
+Embed the content from other notes.
+
+![Note Embed](./assets/screenshots/feature-note-embed.gif)
+
+### Support for sections
+
+Foam supports autocompletion, navigation, embedding and diagnostics for note sections.
+Just use the standard wiki syntax of `[[resource#Section Title]]`.
+
+### Link Alias
+
+Foam supports link aliasing, so you can have a `[[wikilink]]`, or a `[[wikilink|alias]]`.
+
+### Templates
+
+Use [custom templates](https://foambubble.github.io/foam/features/note-templates) to have avoid repetitve work on your notes.
+
+![Templates](./assets/screenshots/feature-templates.gif)
+
+### Backlinks Panel
+
+Quickly check which notes are referencing the currently active note.
+See for each occurrence the context in which it lives, as well as a preview of the note.
+
+![Backlinks Panel](./assets/screenshots/feature-backlinks-panel.gif)
+
+### Tag Explorer Panel
+
+Tag your notes and navigate them with the [Tag Explorer](https://foambubble.github.io/foam/features/tags).
+Foam also supports hierarchical tags.
+
+![Tag Explorer Panel](./assets/screenshots/feature-tags-panel.gif)
+
+### Orphans and Placeholder Panels
+
+Orphans are note that have no inbound nor outbound links. 
+Placeholders are dangling links, or notes without content.
+Keep them under control, and your knowledge base in better state, by using this panel.
+
+![Orphans and Placeholder Panels](./assets/screenshots/feature-placeholder-orphan-panel.gif)
+
+### Syntax highlight
+
+Foam highlights wikilinks and placeholder differently, to help you visualize your knowledge base.
+
+![Syntax Highlight](./assets/screenshots/feature-syntax-highlight.png)
+
+### Daily note
+
+Create a journal with [daily notes](https://foambubble.github.io/foam/features/daily-notes).
+
+![Daily Note](./assets/screenshots/feature-daily-note.gif)
+
+### Generate references for your wikilinks
+
+Create markdown [references](https://foambubble.github.io/foam/features/link-reference-definitions) for `[[wikilinks]]`, to use your notes in a non-Foam workspace.
+With references you can also make your notes navigable both in GitHub UI as well as GitHub Pages.
+
+![Generate references](./assets/screenshots/feature-definitions-generation.gif)
+
+### Commands
+
+- Explore your knowledge base with the `Foam: Open Random Note` command
+- Access your daily note with the `Foam: Open Daily Note` command
+- Create a new note with the `Foam: Create New Note` command
+  - This becomes very powerful when combined with [note templates](https://foambubble.github.io/foam/features/note-templates) and the `Foam: Create New Note from Template` command
+- See your workspace as a connected graph with the `Foam: Show Graph` command
+
+## Recipes
+
+People use Foam in different ways for different use cases, check out the [recipes](https://foambubble.github.io/foam/recipes/recipes) page for inspiration!
+
 ## Getting started
 
 You really, _really_, **really** should read [Foam documentation](https://foambubble.github.io/foam), but if you can't be bothered, this is how to get started:
@@ -22,24 +134,13 @@ You really, _really_, **really** should read [Foam documentation](https://foambu
 2. Clone the repository and open it in VS Code.
 3. When prompted to install recommended extensions, click **Install all** (or **Show Recommendations** if you want to review and install them one by one).
 
-This will also install `Foam for VSCode`, but if you already have it installed, that's ok, just make sure you're up to date on the latest version.
-
-You really, _really_, **really** should read [Foam documentation](https://foambubble.github.io/foam), but if you can't be bothered, this is how to get started:
-
-## Features
-
-- Connect your notes using [`[[wikilinks]]`](https://foambubble.github.io/foam/features/backlinking)
-- Create markdown [references](https://foambubble.github.io/foam/features/link-reference-definitions) for `[[wikilinks]]`, to use your notes in a non-foam workspace
-- See how your notes are connected via a [graph](https://foambubble.github.io/foam/features/graph-visualisation) with the `Foam: Show Graph` command
-- Tag your notes and navigate them with the [Tag Explorer](https://foambubble.github.io/foam/features/tags)
-- Make your notes navigable both in GitHub UI as well as GitHub Pages
-- Use [custom templates](https://foambubble.github.io/foam/features/note-templates) for your notes
-- Create a journal with [daily notes](https://foambubble.github.io/foam/features/daily-notes)
-- Explore your knowledge base with the `Foam: Open Random Note` command
+This will also install `Foam`, but if you already have it installed, that's ok, just make sure you're up to date on the latest version.
 
 ## Requirements
 
 High tolerance for alpha-grade software.
+Foam is still a Work in Progress.
+Rest assured it will never lock you in, nor compromise your files, but sometimes some features might break ;)
 
 ## Known Issues
 

packages/foam-vscode/package.json

@@ -1,20 +1,20 @@
 {
   "name": "foam-vscode",
-  "displayName": "Foam for VSCode (Wikilinks to Markdown)",
-  "description": "Generate markdown reference lists from wikilinks in a workspace",
+  "displayName": "Foam",
+  "description": "VS Code + Markdown + Wikilinks for your note taking and knowledge base",
   "private": true,
   "repository": {
     "url": "https://github.com/foambubble/foam",
     "type": "git"
   },
   "homepage": "https://github.com/foambubble/foam",
-  "version": "0.15.0",
+  "version": "0.17.1",
   "license": "MIT",
   "publisher": "foam",
   "engines": {
     "vscode": "^1.47.1"
   },
-  "icon": "icon/FOAM_ICON_256.png",
+  "icon": "assets/icon/FOAM_ICON_256.png",
   "categories": [
     "Other"
   ],
@@ -223,7 +223,7 @@
         },
         "foam.edit.linkReferenceDefinitions": {
           "type": "string",
-          "default": "withoutExtensions",
+          "default": "off",
           "enum": [
             "withExtensions",
             "withoutExtensions",
@@ -235,11 +235,6 @@
             "Disable wikilink definitions generation"
           ]
         },
-        "foam.links.navigation.enable": {
-          "description": "Enable navigation through links",
-          "type": "boolean",
-          "default": true
-        },
         "foam.links.hover.enable": {
           "description": "Enable displaying note content on hover links",
           "type": "boolean",
@@ -248,7 +243,7 @@
         "foam.decorations.links.enable": {
           "description": "Enable decorations for links",
           "type": "boolean",
-          "default": false
+          "default": true
         },
         "foam.openDailyNote.onStartup": {
           "type": "boolean",
@@ -361,9 +356,11 @@
     "build": "tsc -p ./",
     "pretest": "yarn build",
     "test": "node ./out/test/run-tests.js",
-    "lint": "tsdx lint",
+    "test:unit": "node ./out/test/run-tests.js --unit",
+    "test:e2e": "node ./out/test/run-tests.js --e2e",
+    "lint": "tsdx lint src",
     "clean": "rimraf out",
-    "watch": "tsc --build ./tsconfig.json ../foam-core/tsconfig.json --watch",
+    "watch": "tsc --build ./tsconfig.json --watch",
     "vscode:start-debugging": "yarn clean && yarn watch",
     "vscode:prepublish": "yarn npm-install && yarn run build",
     "npm-install": "rimraf node_modules && npm i",
@@ -376,34 +373,54 @@
   },
   "devDependencies": {
     "@babel/core": "^7.11.0",
+    "@babel/plugin-transform-runtime": "^7.10.4",
     "@babel/preset-env": "^7.11.0",
     "@babel/preset-typescript": "^7.10.4",
     "@types/dateformat": "^3.0.1",
+    "@types/github-slugger": "^1.3.0",
     "@types/glob": "^7.1.1",
+    "@types/lodash": "^4.14.157",
     "@types/markdown-it": "^12.0.1",
+    "@types/micromatch": "^4.0.1",
     "@types/node": "^13.11.0",
+    "@types/picomatch": "^2.2.1",
     "@types/remove-markdown": "^0.1.1",
     "@types/vscode": "^1.47.1",
     "@typescript-eslint/eslint-plugin": "^2.30.0",
     "@typescript-eslint/parser": "^2.30.0",
     "babel-jest": "^26.2.2",
     "eslint": "^6.8.0",
-    "glob": "^7.1.6",
+    "eslint-plugin-import": "^2.24.2",
+    "husky": "^4.2.5",
     "jest": "^26.2.2",
     "jest-environment-vscode": "^1.0.0",
     "jest-extended": "^0.11.5",
     "markdown-it": "^12.0.4",
     "rimraf": "^3.0.2",
     "ts-jest": "^26.4.4",
-    "typescript": "^3.8.3",
+    "tsdx": "^0.13.2",
+    "tslib": "^2.0.0",
+    "typescript": "^3.9.5",
     "vscode-test": "^1.3.0"
   },
   "dependencies": {
     "dateformat": "^3.0.3",
-    "foam-core": "^0.15.0",
+    "detect-newline": "^3.1.0",
+    "fast-array-diff": "^1.0.1",
+    "github-slugger": "^1.3.0",
+    "glob": "^7.1.6",
     "gray-matter": "^4.0.2",
+    "lodash": "^4.17.21",
     "markdown-it-regex": "^0.2.0",
     "micromatch": "^4.0.2",
-    "remove-markdown": "^0.3.0"
+    "remark-frontmatter": "^2.0.0",
+    "remark-parse": "^8.0.2",
+    "remark-wiki-link": "^0.0.4",
+    "remove-markdown": "^0.3.0",
+    "replace-ext": "^2.0.0",
+    "title-case": "^3.0.2",
+    "unified": "^9.0.0",
+    "unist-util-visit": "^2.0.2",
+    "yaml": "^1.10.0"
   }
 }

packages/foam-vscode/src/core/.eslintrc.json

@@ -0,0 +1,36 @@
+{
+  "rules": {
+    "no-restricted-imports": [
+      "error",
+      {
+        "name": "vscode",
+        "message": "Core submodule must not depend on VS Code."
+      }
+    ]
+    // Ideally we would also prevent the core module from depending on other modules
+    // but I have been struggling to get it to work.
+    // For future reference, below are some configurations I think should achieve this
+    // (but I couldn't manage to get working).
+    //
+    // "import/no-internal-modules": [
+    //   "error",
+    //   {
+    //     "allow": ["./src/core"]
+    //   }
+    // ]
+    // "import/no-restricted-paths": [
+    //   "error",
+    //   {
+    //     "zones": [
+    //       {
+    //         "target": "./src/core",
+    //         "from": "./src/(!core)",
+    //         "message": "Core module can't have outside dependencies."
+    //       }
+    //     ]
+    //   }
+    // ]
+    // "import/no-relative-parent-imports": "error"
+    // note:  https://github.com/import-js/eslint-plugin-import/issues/1610
+  }
+}

packages/foam-vscode/src/core/janitor/apply-text-edit.test.ts

@@ -1,6 +1,6 @@
-import { applyTextEdit } from '../../src/janitor/apply-text-edit';
-import { Range } from '../../src/model/range';
-import { Logger } from '../../src/utils/log';
+import { Range } from '../model/range';
+import { Logger } from '../utils/log';
+import { applyTextEdit } from './apply-text-edit';
 
 Logger.setLevel('error');
 

packages/foam-vscode/src/core/janitor/apply-text-edit.ts

@@ -1,7 +1,7 @@
 import os from 'os';
 import detectNewline from 'detect-newline';
 import { Position } from '../model/position';
-import { TextEdit } from '../index';
+import { TextEdit } from '.';
 
 /**
  *

packages/foam-vscode/src/core/janitor/generateHeadings.test.ts

@@ -1,13 +1,12 @@
-import * as path from 'path';
-import { generateHeading } from '../../src/janitor';
-import { createConfigFromFolders } from '../../src/config';
-import { Resource } from '../../src/model/note';
-import { FileDataStore, Matcher } from '../../src/services/datastore';
-import { Logger } from '../../src/utils/log';
-import { FoamWorkspace } from '../../src/model/workspace';
-import { URI } from '../../src/model/uri';
-import { Range } from '../../src/model/range';
-import { MarkdownResourceProvider, bootstrap } from '../../src';
+import { generateHeading } from '.';
+import { TEST_DATA_DIR } from '../../test/test-utils';
+import { MarkdownResourceProvider } from '../markdown-provider';
+import { bootstrap } from '../model/foam';
+import { Resource } from '../model/note';
+import { Range } from '../model/range';
+import { FoamWorkspace } from '../model/workspace';
+import { FileDataStore, Matcher } from '../services/datastore';
+import { Logger } from '../utils/log';
 
 Logger.setLevel('error');
 
@@ -16,21 +15,13 @@ describe('generateHeadings', () => {
   const findBySlug = (slug: string): Resource => {
     return _workspace
       .list()
-      .find(res => URI.getBasename(res.uri) === slug) as Resource;
+      .find(res => res.uri.getName() === slug) as Resource;
   };
 
   beforeAll(async () => {
-    const config = createConfigFromFolders([
-      URI.file(path.join(__dirname, '..', '__scaffold__')),
-    ]);
-    const mdProvider = new MarkdownResourceProvider(
-      new Matcher(
-        config.workspaceFolders,
-        config.includeGlobs,
-        config.ignoreGlobs
-      )
-    );
-    const foam = await bootstrap(config, new FileDataStore(), [mdProvider]);
+    const matcher = new Matcher([TEST_DATA_DIR.joinPath('__scaffold__')]);
+    const mdProvider = new MarkdownResourceProvider(matcher);
+    const foam = await bootstrap(matcher, new FileDataStore(), [mdProvider]);
     _workspace = foam.workspace;
   });
 

packages/foam-vscode/src/core/janitor/generateLinkReferences.test.ts

@@ -1,41 +1,33 @@
-import * as path from 'path';
-import { generateLinkReferences } from '../../src/janitor';
-import { createConfigFromFolders } from '../../src/config';
-import { FileDataStore, Matcher } from '../../src/services/datastore';
-import { Logger } from '../../src/utils/log';
-import { FoamWorkspace } from '../../src/model/workspace';
-import { URI } from '../../src/model/uri';
-import { Resource } from '../../src/model/note';
-import { Range } from '../../src/model/range';
-import { MarkdownResourceProvider, bootstrap } from '../../src';
+import { generateLinkReferences } from '.';
+import { TEST_DATA_DIR } from '../../test/test-utils';
+import { MarkdownResourceProvider } from '../markdown-provider';
+import { bootstrap } from '../model/foam';
+import { Resource } from '../model/note';
+import { Range } from '../model/range';
+import { FoamWorkspace } from '../model/workspace';
+import { FileDataStore, Matcher } from '../services/datastore';
+import { Logger } from '../utils/log';
 
 Logger.setLevel('error');
 
 describe('generateLinkReferences', () => {
   let _workspace: FoamWorkspace;
+  // TODO slug must be reserved for actual slugs, not file names
   const findBySlug = (slug: string): Resource => {
     return _workspace
       .list()
-      .find(res => URI.getBasename(res.uri) === slug) as Resource;
+      .find(res => res.uri.getName() === slug) as Resource;
   };
 
   beforeAll(async () => {
-    const config = createConfigFromFolders([
-      URI.file(path.join(__dirname, '..', '__scaffold__')),
-    ]);
-    const mdProvider = new MarkdownResourceProvider(
-      new Matcher(
-        config.workspaceFolders,
-        config.includeGlobs,
-        config.ignoreGlobs
-      )
-    );
-    const foam = await bootstrap(config, new FileDataStore(), [mdProvider]);
+    const matcher = new Matcher([TEST_DATA_DIR.joinPath('__scaffold__')]);
+    const mdProvider = new MarkdownResourceProvider(matcher);
+    const foam = await bootstrap(matcher, new FileDataStore(), [mdProvider]);
     _workspace = foam.workspace;
   });
 
   it('initialised test graph correctly', () => {
-    expect(_workspace.list().length).toEqual(6);
+    expect(_workspace.list().length).toEqual(10);
   });
 
   it('should add link references to a file that does not have them', () => {
@@ -104,6 +96,54 @@ describe('generateLinkReferences', () => {
 
     expect(actual).toEqual(expected);
   });
+
+  it('should put links with spaces in angel brackets', () => {
+    const note = findBySlug('angel-reference');
+    const expected = {
+      newText: textForNote(
+        note,
+        `
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[Note being refered as angel]: <Note being refered as angel> "Note being refered as angel"
+[//end]: # "Autogenerated link references"`
+      ),
+      range: Range.create(3, 0, 3, 0),
+    };
+
+    const actual = generateLinkReferences(note, _workspace, false);
+
+    expect(actual!.range.start).toEqual(expected.range.start);
+    expect(actual!.range.end).toEqual(expected.range.end);
+    expect(actual!.newText).toEqual(expected.newText);
+  });
+
+  it('should not remove explicitly entered link references', () => {
+    const note = findBySlug('file-with-explicit-link-references');
+    const expected = null;
+
+    const actual = generateLinkReferences(note, _workspace, false);
+
+    expect(actual).toEqual(expected);
+  });
+
+  it('should not remove explicitly entered link references and have an implicit link', () => {
+    const note = findBySlug('file-with-explicit-and-implicit-link-references');
+    const expected = {
+      newText: textForNote(
+        note,
+        `[^footerlink]: https://foambubble.github.io/
+[linkrefenrece]: https://foambubble.github.io/
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[first-document]: first-document "First Document"
+[//end]: # "Autogenerated link references"`
+      ),
+      range: Range.create(5, 0, 10, 42),
+    };
+
+    const actual = generateLinkReferences(note, _workspace, false);
+
+    expect(actual).toEqual(expected);
+  });
 });
 
 /**

packages/foam-vscode/src/core/janitor/index.ts

@@ -59,17 +59,78 @@ export const generateLinkReferences = (
   } else {
     const first = note.definitions[0];
     const last = note.definitions[note.definitions.length - 1];
+
+    var nonGeneratedReferenceDefinitions = note.definitions;
+
+    // if we have more definitions then referenced pages AND the page refers to a page
+    // we expect non-generated link definitions to be present
+    // Collect all non-generated definitions, by removing the generated ones
+    if (
+      note.definitions.length > markdownReferences.length &&
+      markdownReferences.length > 0
+    ) {
+      // remove all autogenerated definitions
+      const beginIndex = note.definitions.findIndex(
+        ({ label }) => label === '//begin'
+      );
+      const endIndex = note.definitions.findIndex(
+        ({ label }) => label === '//end'
+      );
+
+      const generatedDefinitions = [...note.definitions].splice(
+        beginIndex,
+        endIndex - beginIndex + 1
+      );
+
+      nonGeneratedReferenceDefinitions = note.definitions.filter(
+        x => !generatedDefinitions.includes(x)
+      );
+    }
+
+    // When we only have explicitly defined link definitions &&
+    // no indication of previously defined generated links &&
+    // there is no reference to another page, return null
+    if (
+      nonGeneratedReferenceDefinitions.length > 0 &&
+      note.definitions.findIndex(({ label }) => label === '//begin') < 0 &&
+      markdownReferences.length === 0
+    ) {
+      return null;
+    }
+
+    // Format link definitions for non-generated links
+    const nonGeneratedReferences = nonGeneratedReferenceDefinitions
+      .map(stringifyMarkdownLinkReferenceDefinition)
+      .join(note.source.eol);
+
     const oldReferences = note.definitions
       .map(stringifyMarkdownLinkReferenceDefinition)
       .join(note.source.eol);
 
-    if (oldReferences === newReferences) {
+    // When the newly formatted references match the old ones, OR
+    // when non-generated references are present, but no new ones are generated
+    // return null
+    if (
+      oldReferences === newReferences ||
+      (nonGeneratedReferenceDefinitions.length > 0 &&
+        newReferences === '' &&
+        markdownReferences.length > 0)
+    ) {
       return null;
     }
 
+    var fullReferences = `${newReferences}`;
+    // If there are any non-generated definitions, add those to the output as well
+    if (
+      nonGeneratedReferenceDefinitions.length > 0 &&
+      markdownReferences.length > 0
+    ) {
+      fullReferences = `${nonGeneratedReferences}${note.source.eol}${newReferences}`;
+    }
+
     return {
       // @todo: do we need to ensure new lines?
-      newText: `${newReferences}`,
+      newText: `${fullReferences}`,
       range: Range.createFromPosition(first.range!.start, last.range!.end),
     };
   }

packages/foam-vscode/src/core/markdown-provider.test.ts

@@ -2,14 +2,14 @@ import {
   createMarkdownParser,
   createMarkdownReferences,
   ParserPlugin,
-} from '../src/markdown-provider';
-import { DirectLink, WikiLink } from '../src/model/note';
-import { Logger } from '../src/utils/log';
-import { uriToSlug } from '../src/utils/slug';
-import { URI } from '../src/model/uri';
-import { FoamGraph } from '../src/model/graph';
-import { createTestWorkspace } from './core.test';
-import { Range } from '../src/model/range';
+} from './markdown-provider';
+import { DirectLink, WikiLink } from './model/note';
+import { Logger } from './utils/log';
+import { uriToSlug } from './utils/slug';
+import { URI } from './model/uri';
+import { FoamGraph } from './model/graph';
+import { Range } from './model/range';
+import { createTestWorkspace } from '../test/test-utils';
 
 Logger.setLevel('error');
 
@@ -461,6 +461,34 @@ this is some text
   });
 });
 
+describe('Sections plugin', () => {
+  it('should find sections within the note', () => {
+    const note = createNoteFromMarkdown(
+      '/dir1/page-a.md',
+      `
+# Section 1
+
+This is the content of section 1.
+
+## Section 1.1
+
+This is the content of section 1.1.
+
+# Section 2
+
+This is the content of section 2.
+      `
+    );
+    expect(note.sections).toHaveLength(3);
+    expect(note.sections[0].label).toEqual('Section 1');
+    expect(note.sections[0].range).toEqual(Range.create(1, 0, 9, 0));
+    expect(note.sections[1].label).toEqual('Section 1.1');
+    expect(note.sections[1].range).toEqual(Range.create(5, 0, 9, 0));
+    expect(note.sections[2].label).toEqual('Section 2');
+    expect(note.sections[2].range).toEqual(Range.create(9, 0, 13, 0));
+  });
+});
+
 describe('parser plugins', () => {
   const testPlugin: ParserPlugin = {
     visit: (node, note) => {

packages/foam-vscode/src/core/markdown-provider.ts

@@ -17,19 +17,13 @@ import {
 } from './model/note';
 import { Position } from './model/position';
 import { Range } from './model/range';
-import {
-  dropExtension,
-  extractHashtags,
-  extractTagsFromProp,
-  isNone,
-  isSome,
-} from './utils';
+import { extractHashtags, extractTagsFromProp, isNone, isSome } from './utils';
 import { Logger } from './utils/log';
 import { URI } from './model/uri';
 import { FoamWorkspace } from './model/workspace';
-import { ResourceProvider } from 'model/provider';
 import { IDataStore, FileDataStore, IMatcher } from './services/datastore';
-import { IDisposable } from 'common/lifecycle';
+import { IDisposable } from './common/lifecycle';
+import { ResourceProvider } from './model/provider';
 
 const ALIAS_DIVIDER_CHAR = '|';
 
@@ -69,7 +63,7 @@ export class MarkdownResourceProvider implements ResourceProvider {
 
     await Promise.all(
       files.map(async uri => {
-        Logger.info('Found: ' + URI.toString(uri));
+        Logger.info('Found: ' + uri.toString());
         const content = await this.dataStore.read(uri);
         if (isSome(content)) {
           workspace.set(this.parser.parse(uri, content));
@@ -100,15 +94,26 @@ export class MarkdownResourceProvider implements ResourceProvider {
   }
 
   supports(uri: URI) {
-    return URI.isMarkdownFile(uri);
+    return uri.isMarkdown();
   }
 
   read(uri: URI): Promise<string | null> {
     return this.dataStore.read(uri);
   }
 
-  readAsMarkdown(uri: URI): Promise<string | null> {
-    return this.dataStore.read(uri);
+  async readAsMarkdown(uri: URI): Promise<string | null> {
+    let content = await this.dataStore.read(uri);
+    if (isSome(content) && uri.fragment) {
+      const resource = this.parser.parse(uri, content);
+      const section = Resource.findSection(resource, uri.fragment);
+      if (isSome(section)) {
+        const rows = content.split('\n');
+        content = rows
+          .slice(section.range.start.line, section.range.end.line)
+          .join('\n');
+      }
+    }
+    return content;
   }
 
   async fetch(uri: URI) {
@@ -128,21 +133,32 @@ export class MarkdownResourceProvider implements ResourceProvider {
           def => def.label === link.target
         )?.url;
         if (isSome(definitionUri)) {
-          const definedUri = URI.resolve(definitionUri, resource.uri);
+          const definedUri = resource.uri.resolve(definitionUri);
           targetUri =
             workspace.find(definedUri, resource.uri)?.uri ??
             URI.placeholder(definedUri.path);
         } else {
+          const [target, section] = link.target.split('#');
           targetUri =
-            workspace.find(link.target, resource.uri)?.uri ??
-            URI.placeholder(link.target);
+            target === ''
+              ? resource.uri
+              : workspace.find(target, resource.uri)?.uri ??
+                URI.placeholder(link.target);
+
+          if (section) {
+            targetUri = targetUri.withFragment(section);
+          }
         }
         break;
 
       case 'link':
+        const [target, section] = link.target.split('#');
         targetUri =
-          workspace.find(link.target, resource.uri)?.uri ??
-          URI.placeholder(URI.resolve(link.target, resource.uri).path);
+          workspace.find(target, resource.uri)?.uri ??
+          URI.placeholder(resource.uri.resolve(link.target).path);
+        if (section && !targetUri.isPlaceholder()) {
+          targetUri = targetUri.withFragment(section);
+        }
         break;
     }
     return targetUri;
@@ -163,7 +179,7 @@ const getTextFromChildren = (root: Node): string => {
   let text = '';
   visit(root, 'text', node => {
     if (node.type === 'text') {
-      text = text + node.value;
+      text = text + (node as any).value;
     }
   });
   return text;
@@ -201,12 +217,63 @@ const tagsPlugin: ParserPlugin = {
   },
 };
 
+let sectionStack: Array<{ label: string; level: number; start: Position }> = [];
+const sectionsPlugin: ParserPlugin = {
+  name: 'section',
+  onWillVisitTree: () => {
+    sectionStack = [];
+  },
+  visit: (node, note) => {
+    if (node.type === 'heading') {
+      const level = (node as any).depth;
+      const label = ((node as Parent)!.children?.[0] as any)?.value;
+      if (!label || !level) {
+        return;
+      }
+      const start = astPositionToFoamRange(node.position!).start;
+
+      // Close all the sections that are not parents of the current section
+      while (
+        sectionStack.length > 0 &&
+        sectionStack[sectionStack.length - 1].level >= level
+      ) {
+        const section = sectionStack.pop();
+        note.sections.push({
+          label: section.label,
+          range: Range.createFromPosition(section.start, start),
+        });
+      }
+
+      // Add the new section to the stack
+      sectionStack.push({ label, level, start });
+    }
+  },
+  onDidVisitTree: (tree, note) => {
+    const end = Position.create(note.source.end.line + 1, 0);
+    // Close all the remainig sections
+    while (sectionStack.length > 0) {
+      const section = sectionStack.pop();
+      note.sections.push({
+        label: section.label,
+        range: { start: section.start, end },
+      });
+    }
+    note.sections.sort((a, b) =>
+      Position.compareTo(a.range.start, b.range.start)
+    );
+  },
+};
+
 const titlePlugin: ParserPlugin = {
   name: 'title',
   visit: (node, note) => {
-    if (note.title === '' && node.type === 'heading' && node.depth === 1) {
+    if (
+      note.title === '' &&
+      node.type === 'heading' &&
+      (node as any).depth === 1
+    ) {
       note.title =
-        ((node as Parent)!.children?.[0]?.value as string) || note.title;
+        ((node as Parent)!.children?.[0] as any)?.value || note.title;
     }
   },
   onDidFindProperties: (props, note) => {
@@ -215,7 +282,7 @@ const titlePlugin: ParserPlugin = {
   },
   onDidVisitTree: (tree, note) => {
     if (note.title === '') {
-      note.title = URI.getBasename(note.uri);
+      note.title = note.uri.getName();
     }
   },
 };
@@ -224,7 +291,7 @@ const wikilinkPlugin: ParserPlugin = {
   name: 'wikilink',
   visit: (node, note, noteSource) => {
     if (node.type === 'wikiLink') {
-      const text = node.value as string;
+      const text = (node as any).value;
       const alias = node.data?.alias as string;
       const literalContent = noteSource.substring(
         node.position!.start.offset!,
@@ -250,7 +317,7 @@ const wikilinkPlugin: ParserPlugin = {
     }
     if (node.type === 'link') {
       const targetUri = (node as any).url;
-      const uri = URI.resolve(targetUri, note.uri);
+      const uri = note.uri.resolve(targetUri);
       if (uri.scheme !== 'file' || uri.path === note.uri.path) {
         return;
       }
@@ -270,9 +337,9 @@ const definitionsPlugin: ParserPlugin = {
   visit: (node, note) => {
     if (node.type === 'definition') {
       note.definitions.push({
-        label: node.label as string,
-        url: node.url as string,
-        title: node.title as string,
+        label: (node as any).label,
+        url: (node as any).url,
+        title: (node as any).title,
         range: astPositionToFoamRange(node.position!),
       });
     }
@@ -291,7 +358,7 @@ const handleError = (
   const name = plugin.name || '';
   Logger.warn(
     `Error while executing [${fnName}] in plugin [${name}]. ${
-      uri ? 'for file [' + URI.toString(uri) : ']'
+      uri ? 'for file [' + uri.toString() : ']'
     }.`,
     e
   );
@@ -310,6 +377,7 @@ export function createMarkdownParser(
     wikilinkPlugin,
     definitionsPlugin,
     tagsPlugin,
+    sectionsPlugin,
     ...extraPlugins,
   ];
 
@@ -323,7 +391,7 @@ export function createMarkdownParser(
 
   const foamParser: ResourceParser = {
     parse: (uri: URI, markdown: string): Resource => {
-      Logger.debug('Parsing:', URI.toString(uri));
+      Logger.debug('Parsing:', uri.toString());
       markdown = plugins.reduce((acc, plugin) => {
         try {
           return plugin.onWillParseMarkdown?.(acc) || acc;
@@ -340,6 +408,7 @@ export function createMarkdownParser(
         type: 'note',
         properties: {},
         title: '',
+        sections: [],
         tags: [],
         links: [],
         definitions: [],
@@ -361,7 +430,7 @@ export function createMarkdownParser(
       visit(tree, node => {
         if (node.type === 'yaml') {
           try {
-            const yamlProperties = parseYAML(node.value as string) ?? {};
+            const yamlProperties = parseYAML((node as any).value) ?? {};
             note.properties = {
               ...note.properties,
               ...yamlProperties,
@@ -380,10 +449,7 @@ export function createMarkdownParser(
               }
             }
           } catch (e) {
-            Logger.warn(
-              `Error while parsing YAML for [${URI.toString(uri)}]`,
-              e
-            );
+            Logger.warn(`Error while parsing YAML for [${uri.toString()}]`, e);
           }
         }
 
@@ -437,7 +503,9 @@ function getFoamDefinitions(
 export function stringifyMarkdownLinkReferenceDefinition(
   definition: NoteLinkDefinition
 ) {
-  let text = `[${definition.label}]: ${definition.url}`;
+  let url =
+    definition.url.indexOf(' ') > 0 ? `<${definition.url}>` : definition.url;
+  let text = `[${definition.label}]: ${url}`;
   if (definition.title) {
     text = `${text} "${definition.title}"`;
   }
@@ -453,9 +521,8 @@ export function createMarkdownReferences(
   // Should never occur since we're already in a file,
   if (source?.type !== 'note') {
     console.warn(
-      `Note ${URI.toString(
-        noteUri
-      )} note found in workspace when attempting to generate markdown reference list`
+      `Note ${noteUri.toString()} note found in workspace when attempting \
+to generate markdown reference list`
     );
     return [];
   }
@@ -467,9 +534,7 @@ export function createMarkdownReferences(
       const target = workspace.find(targetUri);
       if (isNone(target)) {
         Logger.warn(
-          `Link ${URI.toString(targetUri)} in ${URI.toString(
-            noteUri
-          )} is not valid.`
+          `Link ${targetUri.toString()} in ${noteUri.toString()} is not valid.`
         );
         return null;
       }
@@ -478,10 +543,10 @@ export function createMarkdownReferences(
         return null;
       }
 
-      const relativePath = URI.relativePath(noteUri, target.uri);
-      const pathToNote = includeExtension
-        ? relativePath
-        : dropExtension(relativePath);
+      let relativeUri = target.uri.relativeTo(noteUri.getDirectory());
+      if (!includeExtension) {
+        relativeUri = relativeUri.changeExtension('*', '');
+      }
 
       // [wikilink-text]: path/to/file.md "Page title"
       return {
@@ -489,7 +554,7 @@ export function createMarkdownReferences(
           link.rawText.indexOf('[[') > -1
             ? link.rawText.substring(2, link.rawText.length - 2)
             : link.rawText || link.label,
-        url: pathToNote,
+        url: relativeUri.path,
         title: target.title,
       };
     })

packages/foam-vscode/src/core/model/foam.ts

@@ -1,6 +1,5 @@
 import { IDisposable } from '../common/lifecycle';
-import { IDataStore, IMatcher, Matcher } from '../services/datastore';
-import { FoamConfig } from '../config';
+import { IDataStore, IMatcher } from '../services/datastore';
 import { FoamWorkspace } from './workspace';
 import { FoamGraph } from './graph';
 import { ResourceParser } from './note';
@@ -18,21 +17,15 @@ export interface Foam extends IDisposable {
   services: Services;
   workspace: FoamWorkspace;
   graph: FoamGraph;
-  config: FoamConfig;
   tags: FoamTags;
 }
 
 export const bootstrap = async (
-  config: FoamConfig,
+  matcher: IMatcher,
   dataStore: IDataStore,
   initialProviders: ResourceProvider[]
 ) => {
   const parser = createMarkdownParser([]);
-  const matcher = new Matcher(
-    config.workspaceFolders,
-    config.includeGlobs,
-    config.ignoreGlobs
-  );
   const workspace = new FoamWorkspace();
   await Promise.all(initialProviders.map(p => workspace.registerProvider(p)));
 
@@ -43,7 +36,6 @@ export const bootstrap = async (
     workspace,
     graph,
     tags,
-    config,
     services: {
       dataStore,
       parser,

packages/foam-vscode/src/core/model/graph.ts

@@ -2,9 +2,9 @@ import { diff } from 'fast-array-diff';
 import { isEqual } from 'lodash';
 import { Resource, ResourceLink } from './note';
 import { URI } from './uri';
-import { IDisposable } from '../index';
-import { FoamWorkspace, uriToResourceName } from './workspace';
+import { FoamWorkspace } from './workspace';
 import { Range } from './range';
+import { IDisposable } from '../common/lifecycle';
 
 export type Connection = {
   source: URI;
@@ -99,16 +99,19 @@ export class FoamGraph implements IDisposable {
 
   private updateLinksRelatedToAddedResource(resource: Resource) {
     // check if any existing connection can be filled by new resource
-    const name = uriToResourceName(resource.uri);
-    const placeholder = this.placeholders.get(name);
-    if (placeholder) {
-      this.placeholders.delete(name);
-      const resourcesToUpdate = this.backlinks.get(placeholder.path) ?? [];
-      resourcesToUpdate.forEach(res =>
-        this.resolveResource(this.workspace.get(res.source))
-      );
+    let resourcesToUpdate: URI[] = [];
+    for (const placeholderId of this.placeholders.keys()) {
+      // quick and dirty check for affected resources
+      if (resource.uri.path.endsWith(placeholderId + '.md')) {
+        resourcesToUpdate.push(
+          ...this.backlinks.get(placeholderId).map(c => c.source)
+        );
+        // resourcesToUpdate.push(resource);
+      }
     }
-
+    resourcesToUpdate.forEach(res =>
+      this.resolveResource(this.workspace.get(res))
+    );
     // resolve the resource
     this.resolveResource(resource);
   }
@@ -170,7 +173,7 @@ export class FoamGraph implements IDisposable {
 
     this.backlinks.get(target.path)?.push(connection);
 
-    if (URI.isPlaceholder(target)) {
+    if (target.isPlaceholder()) {
       this.placeholders.set(uriToPlaceholderId(target), target);
     }
     return this;
@@ -190,7 +193,7 @@ export class FoamGraph implements IDisposable {
     const connectionsToKeep =
       link === true
         ? (c: Connection) =>
-            !URI.isEqual(source, c.source) || !URI.isEqual(target, c.target)
+            !source.isEqual(c.source) || !target.isEqual(c.target)
         : (c: Connection) => !isSameConnection({ source, target, link }, c);
 
     this.links.set(
@@ -206,7 +209,7 @@ export class FoamGraph implements IDisposable {
     );
     if (this.backlinks.get(target.path)?.length === 0) {
       this.backlinks.delete(target.path);
-      if (URI.isPlaceholder(target)) {
+      if (target.isPlaceholder()) {
         this.placeholders.delete(uriToPlaceholderId(target));
       }
     }
@@ -232,8 +235,8 @@ export class FoamGraph implements IDisposable {
 // TODO move these utility fns to appropriate places
 
 const isSameConnection = (a: Connection, b: Connection) =>
-  URI.isEqual(a.source, b.source) &&
-  URI.isEqual(a.target, b.target) &&
+  a.source.isEqual(b.source) &&
+  a.target.isEqual(b.target) &&
   isSameLink(a.link, b.link);
 
 const isSameLink = (a: ResourceLink, b: ResourceLink) =>

packages/foam-vscode/src/core/model/note.ts

@@ -38,12 +38,17 @@ export interface Tag {
   range: Range;
 }
 
+export interface Section {
+  label: string;
+  range: Range;
+}
+
 export interface Resource {
   uri: URI;
   type: string;
   title: string;
   properties: any;
-  // sections: NoteSection[]
+  sections: Section[];
   tags: Tag[];
   links: ResourceLink[];
 
@@ -66,7 +71,7 @@ export abstract class Resource {
       return false;
     }
     return (
-      URI.isUri((thing as Resource).uri) &&
+      (thing as Resource).uri instanceof URI &&
       typeof (thing as Resource).title === 'string' &&
       typeof (thing as Resource).type === 'string' &&
       typeof (thing as Resource).properties === 'object' &&
@@ -74,4 +79,11 @@ export abstract class Resource {
       typeof (thing as Resource).links === 'object'
     );
   }
+
+  public static findSection(resource: Resource, label: string): Section | null {
+    if (label) {
+      return resource.sections.find(s => s.label === label) ?? null;
+    }
+    return null;
+  }
 }

packages/foam-vscode/src/core/model/provider.ts

@@ -1,6 +1,6 @@
-import { IDisposable } from 'common/lifecycle';
-import { ResourceLink, URI } from 'index';
-import { Resource } from './note';
+import { IDisposable } from '../common/lifecycle';
+import { Resource, ResourceLink } from './note';
+import { URI } from './uri';
 import { FoamWorkspace } from './workspace';
 
 export interface ResourceProvider extends IDisposable {

packages/foam-vscode/src/core/model/tags.test.ts

@@ -1,5 +1,5 @@
-import { FoamTags } from '../src/model/tags';
-import { createTestNote, createTestWorkspace } from './core.test';
+import { createTestNote, createTestWorkspace } from '../../test/test-utils';
+import { FoamTags } from './tags';
 
 describe('FoamTags', () => {
   it('Collects tags from a list of resources', () => {

packages/foam-vscode/src/core/model/tags.ts

@@ -1,7 +1,7 @@
 import { FoamWorkspace } from './workspace';
 import { URI } from './uri';
-import { IDisposable } from '../index';
 import { Resource } from './note';
+import { IDisposable } from '../common/lifecycle';
 
 export class FoamTags implements IDisposable {
   public readonly tags: Map<string, URI[]> = new Map();
@@ -68,7 +68,7 @@ export class FoamTags implements IDisposable {
       if (this.tags.has(tag)) {
         const remainingLocations = this.tags
           .get(tag)
-          ?.filter(uri => !URI.isEqual(uri, resource.uri));
+          ?.filter(uri => !uri.isEqual(resource.uri));
 
         if (remainingLocations && remainingLocations.length > 0) {
           this.tags.set(tag, remainingLocations);

packages/foam-vscode/src/core/model/uri.test.ts

@@ -0,0 +1,88 @@
+import { Logger } from '../utils/log';
+import { uriToSlug } from '../utils/slug';
+import { URI } from './uri';
+
+Logger.setLevel('error');
+
+describe('Foam URI', () => {
+  describe('URI parsing', () => {
+    const base = URI.file('/path/to/file.md');
+    test.each([
+      ['https://www.google.com', URI.parse('https://www.google.com')],
+      ['/path/to/a/file.md', URI.file('/path/to/a/file.md')],
+      ['../relative/file.md', URI.file('/path/relative/file.md')],
+      ['#section', base.withFragment('section')],
+      [
+        '../relative/file.md#section',
+        URI.parse('file:/path/relative/file.md#section'),
+      ],
+    ])('URI Parsing (%s)', (input, exp) => {
+      const result = base.resolve(input);
+      expect(result.scheme).toEqual(exp.scheme);
+      expect(result.authority).toEqual(exp.authority);
+      expect(result.path).toEqual(exp.path);
+      expect(result.query).toEqual(exp.query);
+      expect(result.fragment).toEqual(exp.fragment);
+    });
+
+    it('normalizes the Windows drive letter to upper case', () => {
+      const upperCase = URI.parse('file:///C:/this/is/a/Path');
+      const lowerCase = URI.parse('file:///c:/this/is/a/Path');
+      expect(upperCase.path).toEqual('/C:/this/is/a/Path');
+      expect(lowerCase.path).toEqual('/C:/this/is/a/Path');
+      expect(upperCase.toFsPath()).toEqual('C:\\this\\is\\a\\Path');
+      expect(lowerCase.toFsPath()).toEqual('C:\\this\\is\\a\\Path');
+    });
+
+    it('consistently parses file paths', () => {
+      const win1 = URI.file('c:\\this\\is\\a\\path');
+      const win2 = URI.parse('c:\\this\\is\\a\\path');
+      expect(win1).toEqual(win2);
+
+      const unix1 = URI.file('/this/is/a/path');
+      const unix2 = URI.parse('/this/is/a/path');
+      expect(unix1).toEqual(unix2);
+    });
+
+    it('correctly parses file paths', () => {
+      const winUri = URI.file('c:\\this\\is\\a\\path');
+      const unixUri = URI.file('/this/is/a/path');
+      expect(winUri).toEqual(
+        new URI({
+          scheme: 'file',
+          path: '/C:/this/is/a/path',
+        })
+      );
+      expect(unixUri).toEqual(
+        new URI({
+          scheme: 'file',
+          path: '/this/is/a/path',
+        })
+      );
+    });
+  });
+
+  it('supports computing relative paths', () => {
+    expect(URI.file('/my/file.md').resolve('../hello.md')).toEqual(
+      URI.file('/hello.md')
+    );
+    expect(URI.file('/my/file.md').resolve('../hello')).toEqual(
+      URI.file('/hello.md')
+    );
+    expect(URI.file('/my/file.markdown').resolve('../hello')).toEqual(
+      URI.file('/hello.markdown')
+    );
+  });
+
+  it('can be slugified', () => {
+    expect(uriToSlug(URI.file('/this/is/a/path.md'))).toEqual('path');
+    expect(uriToSlug(URI.file('../a/relative/path.md'))).toEqual('path');
+    expect(uriToSlug(URI.file('another/relative/path.md'))).toEqual('path');
+    expect(uriToSlug(URI.file('no-directory.markdown'))).toEqual(
+      'no-directory'
+    );
+    expect(uriToSlug(URI.file('many.dots.name.markdown'))).toEqual(
+      'manydotsname'
+    );
+  });
+});

packages/foam-vscode/src/core/model/uri.ts

@@ -4,9 +4,8 @@
 // Some code in this file comes from https://github.com/microsoft/vscode/main/src/vs/base/common/uri.ts
 // See LICENSE for details
 
-import * as paths from 'path';
 import { CharCode } from '../common/charCode';
-import { isWindows } from '../common/platform';
+import * as pathUtils from '../utils/path';
 
 /**
  * Uniform Resource Identifier (URI) http://tools.ietf.org/html/rfc3986.
@@ -24,240 +23,134 @@ import { isWindows } from '../common/platform';
  *       urn:example:animal:ferret:nose
  * ```
  */
-export interface URI {
-  scheme: string;
-  authority: string;
-  path: string;
-  query: string;
-  fragment: string;
-}
 
-const { posix } = paths;
 const _empty = '';
 const _slash = '/';
 const _regexp = /^(([^:/?#]{2,}?):)?(\/\/([^/?#]*))?([^?#]*)(\?([^#]*))?(#(.*))?/;
 
-export abstract class URI {
-  static create(from: Partial<URI>): URI {
-    return {
-      scheme: from.scheme ?? _empty,
-      authority: from.authority ?? _empty,
-      path: from.path ?? _empty,
-      query: from.query ?? _empty,
-      fragment: from.fragment ?? _empty,
-    };
+export class URI {
+  readonly scheme: string;
+  readonly authority: string;
+  readonly path: string;
+  readonly query: string;
+  readonly fragment: string;
+
+  constructor(from: Partial<URI> = {}) {
+    this.scheme = from.scheme ?? _empty;
+    this.authority = from.authority ?? _empty;
+    this.path = from.path ?? _empty; // We assume the path is already posix
+    this.query = from.query ?? _empty;
+    this.fragment = from.fragment ?? _empty;
   }
 
   static parse(value: string): URI {
     const match = _regexp.exec(value);
     if (!match) {
-      return URI.create({});
+      return new URI();
     }
-    return URI.create({
+    return new URI({
       scheme: match[2] || 'file',
       authority: percentDecode(match[4] ?? _empty),
-      path: percentDecode(match[5] ?? _empty),
+      path: pathUtils.fromFsPath(percentDecode(match[5] ?? _empty))[0],
       query: percentDecode(match[7] ?? _empty),
       fragment: percentDecode(match[9] ?? _empty),
     });
   }
 
-  /**
-   * Parses a URI from value, taking into consideration possible relative paths.
-   *
-   * @param reference the URI to use as reference in case value is a relative path
-   * @param value the value to parse for a URI
-   * @returns the URI from the given value. In case of a relative path, the URI will take into account
-   * the reference from which it is computed
-   */
-  static resolve(value: string, reference: URI): URI {
-    let uri = URI.parse(value);
-    if (uri.scheme === 'file' && !value.startsWith('/')) {
-      const [path, fragment] = value.split('#');
-      uri =
-        path.length > 0 ? URI.computeRelativeURI(reference, path) : reference;
-      if (fragment) {
-        uri = URI.create({
-          ...uri,
-          fragment: fragment,
-        });
+  static file(value: string): URI {
+    let [path, authority] = pathUtils.fromFsPath(value);
+    return new URI({ scheme: 'file', authority, path });
+  }
+
+  static placeholder(path: string): URI {
+    return new URI({ scheme: 'placeholder', path: path });
+  }
+
+  resolve(value: string | URI, isDirectory = false): URI {
+    const uri = value instanceof URI ? value : URI.parse(value);
+    if (!uri.isAbsolute()) {
+      if (uri.scheme === 'file' || uri.scheme === 'placeholder') {
+        let newUri = this.withFragment(uri.fragment);
+        if (uri.path) {
+          newUri = (isDirectory ? newUri : newUri.getDirectory())
+            .joinPath(uri.path)
+            .changeExtension('', this.getExtension());
+        }
+        return newUri;
       }
     }
     return uri;
   }
 
-  static computeRelativeURI(reference: URI, relativeSlug: string): URI {
-    // if no extension is provided, use the same extension as the source file
-    const slug =
-      posix.extname(relativeSlug) !== ''
-        ? relativeSlug
-        : `${relativeSlug}${posix.extname(reference.path)}`;
-    return URI.create({
-      ...reference,
-      path: posix.join(posix.dirname(reference.path), slug),
-    });
+  isAbsolute(): boolean {
+    return pathUtils.isAbsolute(this.path);
   }
 
-  static file(path: string): URI {
-    let authority = _empty;
-
-    // normalize to fwd-slashes on windows,
-    // on other systems bwd-slashes are valid
-    // filename character, eg /f\oo/ba\r.txt
-    if (isWindows) {
-      if (path.startsWith(_slash)) {
-        path = `${path.replace(/\\/g, _slash)}`;
-      } else {
-        path = `/${path.replace(/\\/g, _slash)}`;
-      }
-    }
-
-    // check for authority as used in UNC shares
-    // or use the path as given
-    if (path[0] === _slash && path[1] === _slash) {
-      const idx = path.indexOf(_slash, 2);
-      if (idx === -1) {
-        authority = path.substring(2);
-        path = _slash;
-      } else {
-        authority = path.substring(2, idx);
-        path = path.substring(idx) || _slash;
-      }
-    }
-
-    return URI.create({ scheme: 'file', authority, path });
+  getDirectory(): URI {
+    const path = pathUtils.getDirectory(this.path);
+    return new URI({ ...this, path });
   }
 
-  static placeholder(key: string): URI {
-    return URI.create({
-      scheme: 'placeholder',
-      path: key,
-    });
+  getBasename(): string {
+    return pathUtils.getBasename(this.path);
   }
 
-  static relativePath(source: URI, target: URI): string {
-    const relativePath = posix.relative(
-      posix.dirname(source.path),
-      target.path
+  getName(): string {
+    return pathUtils.getName(this.path);
+  }
+
+  getExtension(): string {
+    return pathUtils.getExtension(this.path);
+  }
+
+  changeExtension(from: string, to: string): URI {
+    const path = pathUtils.changeExtension(this.path, from, to);
+    return new URI({ ...this, path });
+  }
+
+  joinPath(...paths: string[]) {
+    const path = pathUtils.joinPath(this.path, ...paths);
+    return new URI({ ...this, path });
+  }
+
+  relativeTo(uri: URI) {
+    const path = pathUtils.relativeTo(this.path, uri.path);
+    return new URI({ ...this, path });
+  }
+
+  withFragment(fragment: string): URI {
+    return new URI({ ...this, fragment });
+  }
+
+  isPlaceholder(): boolean {
+    return this.scheme === 'placeholder';
+  }
+
+  toFsPath() {
+    return pathUtils.toFsPath(
+      this.path,
+      this.scheme === 'file' ? this.authority : ''
     );
-    return relativePath;
   }
 
-  static getBasename(uri: URI) {
-    return posix.parse(uri.path).name;
+  toString(): string {
+    return encode(this, false);
   }
 
-  static getDir(uri: URI) {
-    return URI.file(posix.dirname(uri.path));
+  isMarkdown(): boolean {
+    const ext = this.getExtension();
+    return ext === '.md' || ext === '.markdown';
   }
 
-  static getFileNameWithoutExtension(uri: URI) {
-    return URI.getBasename(uri).replace(/\.[^.]+$/, '');
-  }
-
-  /**
-   * Uses a placeholder URI, and a reference directory, to generate
-   * the URI of the corresponding resource
-   *
-   * @param placeholderUri the placeholder URI
-   * @param basedir the dir to be used as reference
-   * @returns the target resource URI
-   */
-  static createResourceUriFromPlaceholder(
-    basedir: URI,
-    placeholderUri: URI
-  ): URI {
-    const tokens = placeholderUri.path.split('/');
-    const path = tokens.slice(0, -1);
-    const filename = tokens.slice(-1);
-    return URI.joinPath(basedir, ...path, `${filename}.md`);
-  }
-
-  /**
-   * Join a URI path with path fragments and normalizes the resulting path.
-   *
-   * @param uri The input URI.
-   * @param pathFragment The path fragment to add to the URI path.
-   * @returns The resulting URI.
-   */
-  static joinPath(uri: URI, ...pathFragment: string[]): URI {
-    if (!uri.path) {
-      throw new Error(`[UriError]: cannot call joinPath on URI without path`);
-    }
-    let newPath: string;
-    if (isWindows && uri.scheme === 'file') {
-      newPath = URI.file(paths.win32.join(URI.toFsPath(uri), ...pathFragment))
-        .path;
-    } else {
-      newPath = paths.posix.join(uri.path, ...pathFragment);
-    }
-    return URI.create({ ...uri, path: newPath });
-  }
-
-  static toFsPath(uri: URI, keepDriveLetterCasing = true): string {
-    let value: string;
-    if (uri.authority && uri.path.length > 1 && uri.scheme === 'file') {
-      // unc path: file://shares/c$/far/boo
-      value = `//${uri.authority}${uri.path}`;
-    } else if (
-      uri.path.charCodeAt(0) === CharCode.Slash &&
-      ((uri.path.charCodeAt(1) >= CharCode.A &&
-        uri.path.charCodeAt(1) <= CharCode.Z) ||
-        (uri.path.charCodeAt(1) >= CharCode.a &&
-          uri.path.charCodeAt(1) <= CharCode.z)) &&
-      uri.path.charCodeAt(2) === CharCode.Colon
-    ) {
-      if (!keepDriveLetterCasing) {
-        // windows drive letter: file:///c:/far/boo
-        value = uri.path[1].toLowerCase() + uri.path.substr(2);
-      } else {
-        value = uri.path.substr(1);
-      }
-    } else {
-      // other path
-      value = uri.path;
-    }
-    if (isWindows) {
-      value = value.replace(/\//g, '\\');
-    }
-    return value;
-  }
-
-  static toString(uri: URI): string {
-    return encode(uri, false);
-  }
-
-  // --- utility
-
-  static isUri(thing: any): thing is URI {
-    if (!thing) {
-      return false;
-    }
+  isEqual(uri: URI): boolean {
     return (
-      typeof (thing as URI).authority === 'string' &&
-      typeof (thing as URI).fragment === 'string' &&
-      typeof (thing as URI).path === 'string' &&
-      typeof (thing as URI).query === 'string' &&
-      typeof (thing as URI).scheme === 'string'
+      this.authority === uri.authority &&
+      this.scheme === uri.scheme &&
+      this.path === uri.path &&
+      this.fragment === uri.fragment &&
+      this.query === uri.query
     );
   }
-
-  static isPlaceholder(uri: URI): boolean {
-    return uri.scheme === 'placeholder';
-  }
-
-  static isEqual(a: URI, b: URI): boolean {
-    return (
-      a.authority === b.authority &&
-      a.scheme === b.scheme &&
-      a.path === b.path &&
-      a.fragment === b.fragment &&
-      a.query === b.query
-    );
-  }
-  static isMarkdownFile(uri: URI): boolean {
-    return uri.path.endsWith('.md');
-  }
 }
 
 // --- encode / decode
@@ -331,20 +224,20 @@ function encode(uri: URI, skipEncoding: boolean): string {
     }
   }
   if (path) {
-    // lower-case windows drive letters in /C:/fff or C:/fff
+    // upper-case windows drive letters in /c:/fff or c:/fff
     if (
       path.length >= 3 &&
       path.charCodeAt(0) === CharCode.Slash &&
       path.charCodeAt(2) === CharCode.Colon
     ) {
       const code = path.charCodeAt(1);
-      if (code >= CharCode.A && code <= CharCode.Z) {
-        path = `/${String.fromCharCode(code + 32)}:${path.substr(3)}`; // "/c:".length === 3
+      if (code >= CharCode.a && code <= CharCode.z) {
+        path = `/${String.fromCharCode(code - 32)}:${path.substr(3)}`; // "/C:".length === 3
       }
     } else if (path.length >= 2 && path.charCodeAt(1) === CharCode.Colon) {
       const code = path.charCodeAt(0);
-      if (code >= CharCode.A && code <= CharCode.Z) {
-        path = `${String.fromCharCode(code + 32)}:${path.substr(2)}`; // "/c:".length === 3
+      if (code >= CharCode.a && code <= CharCode.z) {
+        path = `${String.fromCharCode(code - 32)}:${path.substr(2)}`; // "/C:".length === 3
       }
     }
     // encode the rest of the path

packages/foam-vscode/src/core/model/workspace.test.ts

@@ -1,29 +1,11 @@
-import { getReferenceType } from '../src/model/workspace';
-import { FoamGraph } from '../src/model/graph';
-import { Logger } from '../src/utils/log';
-import { createTestNote, createTestWorkspace } from './core.test';
-import { URI } from '../src/model/uri';
+import { FoamWorkspace } from './workspace';
+import { FoamGraph } from './graph';
+import { Logger } from '../utils/log';
+import { URI } from './uri';
+import { createTestNote, createTestWorkspace } from '../../test/test-utils';
 
 Logger.setLevel('error');
 
-describe('Reference types', () => {
-  it('Detects absolute references', () => {
-    expect(getReferenceType('/hello')).toEqual('absolute-path');
-    expect(getReferenceType('/hello/there')).toEqual('absolute-path');
-  });
-  it('Detects relative references', () => {
-    expect(getReferenceType('../hello')).toEqual('relative-path');
-    expect(getReferenceType('./hello')).toEqual('relative-path');
-    expect(getReferenceType('./hello/there')).toEqual('relative-path');
-  });
-  it('Detects key references', () => {
-    expect(getReferenceType('hello')).toEqual('key');
-  });
-  it('Detects URIs', () => {
-    expect(getReferenceType(URI.file('/path/to/file.md'))).toEqual('uri');
-  });
-});
-
 describe('Workspace resources', () => {
   it('Adds notes to workspace', () => {
     const ws = createTestWorkspace();
@@ -71,6 +53,41 @@ describe('Workspace resources', () => {
     ws.set(noteA);
     expect(ws.list()).toEqual([noteA]);
   });
+
+  it('#851 - listing by ID should not return files with same suffix', () => {
+    const ws = createTestWorkspace()
+      .set(createTestNote({ uri: 'test-file.md' }))
+      .set(createTestNote({ uri: 'file.md' }));
+    expect(ws.listByIdentifier('file').length).toEqual(1);
+  });
+
+  it('Support dendron-style names', () => {
+    const ws = createTestWorkspace()
+      .set(createTestNote({ uri: 'note.pdf' }))
+      .set(createTestNote({ uri: 'note.md' }))
+      .set(createTestNote({ uri: 'note.yo.md' }))
+      .set(createTestNote({ uri: 'note2.md' }));
+    for (const [reference, path] of [
+      ['note', '/note.md'],
+      ['note.md', '/note.md'],
+      ['note.yo', '/note.yo.md'],
+      ['note.yo.md', '/note.yo.md'],
+      ['note.pdf', '/note.pdf'],
+      ['note2', '/note2.md'],
+    ]) {
+      expect(ws.listByIdentifier(reference)[0].uri.path).toEqual(path);
+      expect(ws.find(reference).uri.path).toEqual(path);
+    }
+  });
+
+  it('Should include fragment when finding resource URI', () => {
+    const ws = createTestWorkspace()
+      .set(createTestNote({ uri: 'test-file.md' }))
+      .set(createTestNote({ uri: 'file.md' }));
+
+    const res = ws.find('test-file#my-section');
+    expect(res.uri.fragment).toEqual('my-section');
+  });
 });
 
 describe('Graph', () => {
@@ -146,6 +163,86 @@ describe('Graph', () => {
   });
 });
 
+describe('Identifier computation', () => {
+  it('should compute the minimum identifier to resolve a name clash', () => {
+    const first = createTestNote({
+      uri: '/path/to/page-a.md',
+    });
+    const second = createTestNote({
+      uri: '/another/way/for/page-a.md',
+    });
+    const third = createTestNote({
+      uri: '/another/path/for/page-a.md',
+    });
+    const ws = new FoamWorkspace()
+      .set(first)
+      .set(second)
+      .set(third);
+
+    expect(ws.getIdentifier(first.uri)).toEqual('to/page-a');
+    expect(ws.getIdentifier(second.uri)).toEqual('way/for/page-a');
+    expect(ws.getIdentifier(third.uri)).toEqual('path/for/page-a');
+  });
+
+  it('should support sections in identifier computation', () => {
+    const first = createTestNote({
+      uri: '/path/to/page-a.md',
+    });
+    const second = createTestNote({
+      uri: '/another/way/for/page-a.md',
+    });
+    const third = createTestNote({
+      uri: '/another/path/for/page-a.md',
+    });
+    const ws = new FoamWorkspace()
+      .set(first)
+      .set(second)
+      .set(third);
+
+    expect(ws.getIdentifier(first.uri.withFragment('section name'))).toEqual(
+      'to/page-a#section name'
+    );
+  });
+
+  const needle = '/project/car/todo';
+
+  test.each([
+    [['/project/home/todo', '/other/todo', '/something/else'], 'car/todo'],
+    [['/family/car/todo', '/other/todo'], 'project/car/todo'],
+    [[], 'todo'],
+  ])('Find shortest identifier', (haystack, id) => {
+    expect(FoamWorkspace.getShortestIdentifier(needle, haystack)).toEqual(id);
+  });
+
+  it('should ignore same string in haystack', () => {
+    const haystack = [
+      needle,
+      '/project/home/todo',
+      '/other/todo',
+      '/something/else',
+    ];
+    const identifier = FoamWorkspace.getShortestIdentifier(needle, haystack);
+    expect(identifier).toEqual('car/todo');
+  });
+
+  it('should return best guess when no solution is possible', () => {
+    /**
+     * In this case there is no way to uniquely identify the element,
+     * our fallback is to just return the "least wrong" result, basically
+     * a full identifier
+     * This is an edge case that should never happen in a real repo
+     */
+    const haystack = [
+      '/parent/' + needle,
+      '/project/home/todo',
+      '/other/todo',
+      '/something/else',
+    ];
+    const identifier = FoamWorkspace.getShortestIdentifier(needle, haystack);
+    expect(identifier).toEqual('project/car/todo');
+  });
+});
+
 describe('Wikilinks', () => {
   it('Can be defined with basename, relative path, absolute path, extension', () => {
     const noteA = createTestNote({
@@ -313,15 +410,14 @@ describe('Wikilinks', () => {
     expect(graph.getBacklinks(attachmentA.uri).map(l => l.source)).toEqual([
       noteA.uri,
     ]);
-    expect(graph.getBacklinks(attachmentB.uri).map(l => l.source)).toEqual([
-      noteA.uri,
-    ]);
+    // Attachments require extension
+    expect(graph.getBacklinks(attachmentB.uri).map(l => l.source)).toEqual([]);
   });
 
   it('Resolves conflicts alphabetically - part 1', () => {
     const noteA = createTestNote({
       uri: '/path/to/page-a.md',
-      links: [{ slug: 'attachment-a' }],
+      links: [{ slug: 'attachment-a.pdf' }],
     });
     const attachmentA = createTestNote({
       uri: '/path/to/more/attachment-a.pdf',
@@ -343,7 +439,7 @@ describe('Wikilinks', () => {
   it('Resolves conflicts alphabetically - part 2', () => {
     const noteA = createTestNote({
       uri: '/path/to/page-a.md',
-      links: [{ slug: 'attachment-a' }],
+      links: [{ slug: 'attachment-a.pdf' }],
     });
     const attachmentA = createTestNote({
       uri: '/path/to/more/attachment-a.pdf',
@@ -362,21 +458,7 @@ describe('Wikilinks', () => {
     ]);
   });
 
-  it('Allows for dendron-style wikilinks, including a dot', () => {
-    const noteA = createTestNote({
-      uri: '/path/to/page-a.md',
-      links: [{ slug: 'dendron.style' }],
-    });
-    const noteB1 = createTestNote({ uri: '/path/to/another/dendron.style.md' });
-
-    const ws = createTestWorkspace();
-    ws.set(noteA).set(noteB1);
-    const graph = FoamGraph.fromWorkspace(ws);
-
-    expect(graph.getLinks(noteA.uri).map(l => l.target)).toEqual([noteB1.uri]);
-  });
-
-  it('Handles capatalization of files and wikilinks correctly', () => {
+  it('Handles capitalization of files and wikilinks correctly', () => {
     const noteA = createTestNote({
       uri: '/path/to/page-a.md',
       links: [
@@ -408,7 +490,7 @@ describe('Wikilinks', () => {
   });
 });
 
-describe('markdown direct links', () => {
+describe('Markdown direct links', () => {
   it('Support absolute and relative path', () => {
     const noteA = createTestNote({
       uri: '/path/to/page-a.md',

packages/foam-vscode/src/core/model/workspace.ts

@@ -0,0 +1,199 @@
+import { Resource, ResourceLink } from './note';
+import { URI } from './uri';
+import { isAbsolute, getExtension, changeExtension } from '../utils/path';
+import { isSome } from '../utils';
+import { Emitter } from '../common/event';
+import { ResourceProvider } from './provider';
+import { IDisposable } from '../common/lifecycle';
+
+export class FoamWorkspace implements IDisposable {
+  private onDidAddEmitter = new Emitter<Resource>();
+  private onDidUpdateEmitter = new Emitter<{ old: Resource; new: Resource }>();
+  private onDidDeleteEmitter = new Emitter<Resource>();
+  onDidAdd = this.onDidAddEmitter.event;
+  onDidUpdate = this.onDidUpdateEmitter.event;
+  onDidDelete = this.onDidDeleteEmitter.event;
+
+  private providers: ResourceProvider[] = [];
+
+  /**
+   * Resources by path
+   */
+  private resources: Map<string, Resource> = new Map();
+
+  registerProvider(provider: ResourceProvider) {
+    this.providers.push(provider);
+    return provider.init(this);
+  }
+
+  set(resource: Resource) {
+    const old = this.find(resource.uri);
+    this.resources.set(normalize(resource.uri.path), resource);
+    isSome(old)
+      ? this.onDidUpdateEmitter.fire({ old: old, new: resource })
+      : this.onDidAddEmitter.fire(resource);
+    return this;
+  }
+
+  delete(uri: URI) {
+    const deleted = this.resources.get(normalize(uri.path));
+    this.resources.delete(normalize(uri.path));
+
+    isSome(deleted) && this.onDidDeleteEmitter.fire(deleted);
+    return deleted ?? null;
+  }
+
+  public exists(uri: URI): boolean {
+    return isSome(this.find(uri));
+  }
+
+  public list(): Resource[] {
+    return Array.from(this.resources.values());
+  }
+
+  public get(uri: URI): Resource {
+    const note = this.find(uri);
+    if (isSome(note)) {
+      return note;
+    } else {
+      throw new Error('Resource not found: ' + uri.path);
+    }
+  }
+
+  public listByIdentifier(identifier: string): Resource[] {
+    let needle = normalize('/' + identifier);
+    let mdNeedle = getExtension(needle) !== '.md' ? needle + '.md' : undefined;
+    let resources = [];
+    for (const key of this.resources.keys()) {
+      if ((mdNeedle && key.endsWith(mdNeedle)) || key.endsWith(needle)) {
+        resources.push(this.resources.get(normalize(key)));
+      }
+    }
+    return resources.sort((a, b) => a.uri.path.localeCompare(b.uri.path));
+  }
+
+  /**
+   * Returns the minimal identifier for the given resource
+   *
+   * @param forResource the resource to compute the identifier for
+   */
+  public getIdentifier(forResource: URI): string {
+    const amongst = [];
+    const basename = forResource.getBasename();
+    for (const res of this.resources.values()) {
+      // Just a quick optimization to only add the elements that might match
+      if (res.uri.path.endsWith(basename)) {
+        if (!res.uri.isEqual(forResource)) {
+          amongst.push(res.uri);
+        }
+      }
+    }
+    let identifier = FoamWorkspace.getShortestIdentifier(
+      forResource.path,
+      amongst.map(uri => uri.path)
+    );
+    identifier = changeExtension(identifier, '.md', '');
+    if (forResource.fragment) {
+      identifier += `#${forResource.fragment}`;
+    }
+    return identifier;
+  }
+
+  public find(reference: URI | string, baseUri?: URI): Resource | null {
+    if (reference instanceof URI) {
+      return this.resources.get(normalize((reference as URI).path)) ?? null;
+    }
+    let resource: Resource | null = null;
+    let [path, fragment] = (reference as string).split('#');
+    if (FoamWorkspace.isIdentifier(path)) {
+      resource = this.listByIdentifier(path)[0];
+    } else {
+      if (isAbsolute(path) || isSome(baseUri)) {
+        if (getExtension(path) !== '.md') {
+          const uri = baseUri.resolve(path + '.md');
+          resource = uri ? this.resources.get(normalize(uri.path)) : null;
+        }
+        if (!resource) {
+          const uri = baseUri.resolve(path);
+          resource = uri ? this.resources.get(normalize(uri.path)) : null;
+        }
+      }
+    }
+    if (resource && fragment) {
+      resource = { ...resource, uri: resource.uri.withFragment(fragment) };
+    }
+    return resource ?? null;
+  }
+
+  public resolveLink(resource: Resource, link: ResourceLink): URI {
+    // TODO add tests
+    const provider = this.providers.find(p => p.supports(resource.uri));
+    return (
+      provider?.resolveLink(this, resource, link) ??
+      URI.placeholder(link.target)
+    );
+  }
+
+  public read(uri: URI): Promise<string | null> {
+    const provider = this.providers.find(p => p.supports(uri));
+    return provider?.read(uri) ?? Promise.resolve(null);
+  }
+
+  public readAsMarkdown(uri: URI): Promise<string | null> {
+    const provider = this.providers.find(p => p.supports(uri));
+    return provider?.readAsMarkdown(uri) ?? Promise.resolve(null);
+  }
+
+  public dispose(): void {
+    this.onDidAddEmitter.dispose();
+    this.onDidDeleteEmitter.dispose();
+    this.onDidUpdateEmitter.dispose();
+  }
+
+  static isIdentifier(path: string): boolean {
+    return !(
+      path.startsWith('/') ||
+      path.startsWith('./') ||
+      path.startsWith('../')
+    );
+  }
+
+  /**
+   * Returns the minimal identifier for the given string amongst others
+   *
+   * @param forPath the value to compute the identifier for
+   * @param amongst the set of strings within which to find the identifier
+   */
+  static getShortestIdentifier(forPath: string, amongst: string[]): string {
+    const needleTokens = forPath.split('/').reverse();
+    const haystack = amongst
+      .filter(value => value !== forPath)
+      .map(value => value.split('/').reverse());
+
+    let tokenIndex = 0;
+    let res = needleTokens;
+    while (tokenIndex < needleTokens.length) {
+      for (let j = haystack.length - 1; j >= 0; j--) {
+        if (
+          haystack[j].length < tokenIndex ||
+          needleTokens[tokenIndex] !== haystack[j][tokenIndex]
+        ) {
+          haystack.splice(j, 1);
+        }
+      }
+      if (haystack.length === 0) {
+        res = needleTokens.splice(0, tokenIndex + 1);
+        break;
+      }
+      tokenIndex++;
+    }
+    const identifier = res
+      .filter(token => token.trim() !== '')
+      .reverse()
+      .join('/');
+
+    return identifier;
+  }
+}
+
+const normalize = (v: string) => v.toLocaleLowerCase();

packages/foam-vscode/src/core/services/datastore.test.ts

@@ -1,18 +1,18 @@
-import { Logger } from '../src/utils/log';
-import { URI } from '../src/model/uri';
-import { FileDataStore, Matcher } from '../src';
-import { toMatcherPathFormat } from '../src/services/datastore';
+import { TEST_DATA_DIR } from '../../test/test-utils';
+import { URI } from '../model/uri';
+import { Logger } from '../utils/log';
+import { FileDataStore, Matcher, toMatcherPathFormat } from './datastore';
 
 Logger.setLevel('error');
 
-const testFolder = URI.joinPath(URI.file(__dirname), 'test-datastore');
+const testFolder = TEST_DATA_DIR.joinPath('test-datastore');
 
 describe('Matcher', () => {
   it('generates globs with the base dir provided', () => {
     const matcher = new Matcher([testFolder], ['*'], []);
     expect(matcher.folders).toEqual([toMatcherPathFormat(testFolder)]);
     expect(matcher.include).toEqual([
-      toMatcherPathFormat(URI.joinPath(testFolder, '*')),
+      toMatcherPathFormat(testFolder.joinPath('*')),
     ]);
   });
 
@@ -20,7 +20,7 @@ describe('Matcher', () => {
     const matcher = new Matcher([testFolder]);
     expect(matcher.exclude).toEqual([]);
     expect(matcher.include).toEqual([
-      toMatcherPathFormat(URI.joinPath(testFolder, '**', '*')),
+      toMatcherPathFormat(testFolder.joinPath('**', '*')),
     ]);
   });
 
@@ -28,32 +28,32 @@ describe('Matcher', () => {
     const matcher = new Matcher([testFolder], ['g1', 'g2'], []);
     expect(matcher.exclude).toEqual([]);
     expect(matcher.include).toEqual([
-      toMatcherPathFormat(URI.joinPath(testFolder, 'g1')),
-      toMatcherPathFormat(URI.joinPath(testFolder, 'g2')),
+      toMatcherPathFormat(testFolder.joinPath('g1')),
+      toMatcherPathFormat(testFolder.joinPath('g2')),
     ]);
   });
 
   it('has a match method to filter strings', () => {
     const matcher = new Matcher([testFolder], ['*.md'], []);
     const files = [
-      URI.joinPath(testFolder, 'file1.md'),
-      URI.joinPath(testFolder, 'file2.md'),
-      URI.joinPath(testFolder, 'file3.mdx'),
-      URI.joinPath(testFolder, 'sub', 'file4.md'),
+      testFolder.joinPath('file1.md'),
+      testFolder.joinPath('file2.md'),
+      testFolder.joinPath('file3.mdx'),
+      testFolder.joinPath('sub', 'file4.md'),
     ];
     expect(matcher.match(files)).toEqual([
-      URI.joinPath(testFolder, 'file1.md'),
-      URI.joinPath(testFolder, 'file2.md'),
+      testFolder.joinPath('file1.md'),
+      testFolder.joinPath('file2.md'),
     ]);
   });
 
   it('has a isMatch method to see whether a file is matched or not', () => {
     const matcher = new Matcher([testFolder], ['*.md'], []);
     const files = [
-      URI.joinPath(testFolder, 'file1.md'),
-      URI.joinPath(testFolder, 'file2.md'),
-      URI.joinPath(testFolder, 'file3.mdx'),
-      URI.joinPath(testFolder, 'sub', 'file4.md'),
+      testFolder.joinPath('file1.md'),
+      testFolder.joinPath('file2.md'),
+      testFolder.joinPath('file3.mdx'),
+      testFolder.joinPath('sub', 'file4.md'),
     ];
     expect(matcher.isMatch(files[0])).toEqual(true);
     expect(matcher.isMatch(files[1])).toEqual(true);
@@ -72,10 +72,10 @@ describe('Matcher', () => {
   it('ignores files in the exclude list', () => {
     const matcher = new Matcher([testFolder], ['*.md'], ['file1.*']);
     const files = [
-      URI.joinPath(testFolder, 'file1.md'),
-      URI.joinPath(testFolder, 'file2.md'),
-      URI.joinPath(testFolder, 'file3.mdx'),
-      URI.joinPath(testFolder, 'sub', 'file4.md'),
+      testFolder.joinPath('file1.md'),
+      testFolder.joinPath('file2.md'),
+      testFolder.joinPath('file3.mdx'),
+      testFolder.joinPath('sub', 'file4.md'),
     ];
     expect(matcher.isMatch(files[0])).toEqual(false);
     expect(matcher.isMatch(files[1])).toEqual(true);

packages/foam-vscode/src/core/services/datastore.ts

@@ -39,8 +39,8 @@ export interface IMatcher {
  * we convert the fs path on the way in and out
  */
 export const toMatcherPathFormat = isWindows
-  ? (uri: URI) => URI.toFsPath(uri).replace(/\\/g, '/')
-  : (uri: URI) => URI.toFsPath(uri);
+  ? (uri: URI) => uri.toFsPath().replace(/\\/g, '/')
+  : (uri: URI) => uri.toFsPath();
 
 export const toFsPath = isWindows
   ? (path: string): string => path.replace(/\//g, '\\')
@@ -76,7 +76,7 @@ export class Matcher implements IMatcher {
 
   match(files: URI[]) {
     const matches = micromatch(
-      files.map(f => URI.toFsPath(f)),
+      files.map(f => f.toFsPath()),
       this.include,
       {
         ignore: this.exclude,
@@ -123,7 +123,7 @@ export class FileDataStore implements IDataStore {
 
   async read(uri: URI) {
     try {
-      return (await fs.promises.readFile(URI.toFsPath(uri))).toString();
+      return (await fs.promises.readFile(uri.toFsPath())).toString();
     } catch (e) {
       Logger.error(
         `FileDataStore: error while reading uri: ${uri.path} - ${e}`

packages/foam-vscode/src/core/utils/core.ts

@@ -1,19 +1,19 @@
 import crypto from 'crypto';
 
 export function isNotNull<T>(value: T | null): value is T {
-  return value != null;
+  return value != null; // eslint-disable-line
 }
 
 export function isSome<T>(
   value: T | null | undefined | void
 ): value is NonNullable<T> {
-  return value != null;
+  return value != null; // eslint-disable-line
 }
 
 export function isNone<T>(
   value: T | null | undefined | void
 ): value is null | undefined | void {
-  return value == null;
+  return value == null; // eslint-disable-line
 }
 
 export function isNumeric(value: string): boolean {

packages/foam-vscode/src/core/utils/index.ts

@@ -2,12 +2,6 @@ import { titleCase } from 'title-case';
 export { extractHashtags, extractTagsFromProp } from './hashtags';
 export * from './core';
 
-export function dropExtension(path: string): string {
-  const parts = path.split('.');
-  parts.pop();
-  return parts.join('.');
-}
-
 /**
  *
  * @param filename

packages/foam-vscode/src/core/utils/path.ts

@@ -0,0 +1,192 @@
+import { CharCode } from '../common/charCode';
+import { posix } from 'path';
+import { promises, constants } from 'fs';
+
+/**
+ * Converts filesystem path to POSIX path. Supported inputs are:
+ *   - Windows path starting with a drive letter, e.g. C:\dir\file.ext
+ *   - UNC path for a shared file, e.g. \\server\share\path\file.ext
+ *   - POSIX path, e.g. /dir/file.ext
+ *
+ * @param path A supported filesystem path.
+ * @returns [path, authority] where path is a POSIX representation for the
+ *     given input and authority is undefined except for UNC paths.
+ */
+export function fromFsPath(path: string): [string, string] {
+  let authority: string;
+  if (isUNCShare(path)) {
+    [path, authority] = parseUNCShare(path);
+    path = path.replace(/\\/g, '/');
+  } else if (hasDrive(path)) {
+    path = '/' + path[0].toUpperCase() + path.substr(1).replace(/\\/g, '/');
+  } else if (path[0] === '/' && hasDrive(path, 1)) {
+    // POSIX representation of a Windows path: just normalize drive letter case
+    path = '/' + path[1].toUpperCase() + path.substr(2);
+  }
+  return [path, authority];
+}
+
+/**
+ * Converts a POSIX path to a filesystem path.
+ *
+ * @param path A POSIX path.
+ * @param authority An optional authority used to build UNC paths. This only
+ *     makes sense for the Windows platform.
+ * @returns A platform-specific representation of the given POSIX path.
+ */
+export function toFsPath(path: string, authority?: string): string {
+  if (path[0] === '/' && hasDrive(path, 1)) {
+    path = path.substr(1).replace(/\//g, '\\');
+    if (authority) {
+      path = `\\\\${authority}${path}`;
+    }
+  }
+  return path;
+}
+
+/**
+ * Extracts the containing directory of a POSIX path, e.g.
+ *    - /d1/d2/f.ext -> /d1/d2
+ *    - /d1/d2 -> /d1
+ *
+ * @param path A POSIX path.
+ * @returns true if the path is absolute, false otherwise.
+ */
+export function isAbsolute(path: string): boolean {
+  return posix.isAbsolute(path);
+}
+
+/**
+ * Extracts the containing directory of a POSIX path, e.g.
+ *    - /d1/d2/f.ext -> /d1/d2
+ *    - /d1/d2 -> /d1
+ *
+ * @param path A POSIX path.
+ * @returns The containing directory of the given path.
+ */
+export function getDirectory(path: string): string {
+  return posix.dirname(path);
+}
+
+/**
+ * Extracts the basename of a POSIX path, e.g. /d/f.ext -> f.ext.
+ *
+ * @param path A POSIX path.
+ * @returns The basename of the given path.
+ */
+export function getBasename(path: string): string {
+  return posix.basename(path);
+}
+
+/**
+ * Extracts the name of a POSIX path, e.g. /d/f.ext -> f.
+ *
+ * @param path A POSIX path.
+ * @returns The name of the given path.
+ */
+export function getName(path: string): string {
+  return changeExtension(getBasename(path), '*', '');
+}
+
+/**
+ * Extracts the extension of a POSIX path, e.g.
+ *    - /d/f.ext -> .ext
+ *    - /d/f.g.ext -> .ext
+ *    - /d/f -> ''
+ *
+ * @param path A POSIX path.
+ * @returns The extension of the given path.
+ */
+export function getExtension(path: string): string {
+  return posix.extname(path);
+}
+
+/**
+ * Changes a POSIX path matching some extension to have another extension.
+ *
+ * @param path A POSIX path.
+ * @param from The required current extension, or '*' to match any extension.
+ * @param to The target extension.
+ * @returns A POSIX path with its extension possibly changed.
+ */
+export function changeExtension(
+  path: string,
+  from: string,
+  to: string
+): string {
+  const old = getExtension(path);
+  if ((from === '*' && old !== to) || old === from) {
+    path = path.substring(0, path.length - old.length);
+    return to ? path + to : path;
+  }
+  return path;
+}
+
+/**
+ * Joins a number of POSIX paths into a single POSIX path, e.g.
+ *    - /d1, d2, f.ext -> /d1/d2/f.ext
+ *    - /d1/d2, .., f.ext -> /d1/f.ext
+ *
+ * @param paths A variable number of POSIX paths.
+ * @returns A POSIX path built from the given POSIX paths.
+ */
+export function joinPath(...paths: string[]): string {
+  return posix.join(...paths);
+}
+
+/**
+ * Makes a POSIX path relative to another POSIX path, e.g.
+ *    - /d1/d2 relative to /d1 -> d2
+ *    - /d1/d2 relative to /d1/d3 -> ../d2
+ *
+ * @param path The POSIX path to be made relative.
+ * @param basePath The POSIX base path.
+ * @returns A POSIX path relative to the base path.
+ */
+export function relativeTo(path: string, basePath: string): string {
+  return posix.relative(basePath, path);
+}
+
+/**
+ * Asynchronously checks if there is an accessible file for a path.
+ *
+ * @param fsPath A filesystem-specific path.
+ * @returns true if an accesible file exists, false otherwise.
+ */
+export async function existsInFs(fsPath: string) {
+  try {
+    await promises.access(fsPath, constants.F_OK);
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+function hasDrive(path: string, idx = 0): boolean {
+  if (path.length <= idx) {
+    return false;
+  }
+  const c = path.charCodeAt(idx);
+  return (
+    ((c >= CharCode.A && c <= CharCode.Z) ||
+      (c >= CharCode.a && c <= CharCode.z)) &&
+    path.charCodeAt(idx + 1) === CharCode.Colon
+  );
+}
+
+function isUNCShare(fsPath: string): boolean {
+  return (
+    fsPath.length >= 2 &&
+    fsPath.charCodeAt(0) === CharCode.Backslash &&
+    fsPath.charCodeAt(1) === CharCode.Backslash
+  );
+}
+
+function parseUNCShare(uncPath: string): [string, string] {
+  const idx = uncPath.indexOf('\\', 2);
+  if (idx === -1) {
+    return [uncPath.substring(2), '\\'];
+  } else {
+    return [uncPath.substring(2, idx), uncPath.substring(idx) || '\\'];
+  }
+}