diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 000000000..e11b922d8 --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,10 @@ +{ + "name": "Foam Dev Container", + "image": "mcr.microsoft.com/devcontainers/typescript-node:0-18", + "postCreateCommand": "yarn install", + "customizations": { + "vscode": { + "extensions": ["dbaeumer.vscode-eslint", "esbenp.prettier-vscode"] + } + } +} diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 70dc38d16..c73d48310 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -73,4 +73,4 @@ jobs: - name: Run Tests uses: GabrielBB/xvfb-action@v1.4 with: - run: yarn test --stream + run: yarn test diff --git a/.vscode/settings.json b/.vscode/settings.json index 16c0c76e3..f8c0f26aa 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -24,9 +24,8 @@ "editor.formatOnSave": true, "editor.formatOnSaveMode": "file", "editor.defaultFormatter": "esbenp.prettier-vscode", - "jest.autoRun": "off", "jest.rootPath": "packages/foam-vscode", - "jest.jestCommandLine": "yarn jest", + "jest.jestCommandLine": "yarn test:unit-with-specs", "gitdoc.enabled": false, "search.mode": "reuseEditor", "[typescript]": { diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..f0a606cfe --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,212 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Quick Commands + +### Development + +- `yarn install` - Install dependencies +- `yarn build` - Build all packages +- `yarn watch` - Watch mode for development +- `yarn clean` - Clean build outputs +- `yarn reset` - Full clean, install, and build + +### Testing + +- `yarn test` - Run all tests (unit + integration) +- `yarn test:unit-with-specs` - Run only unit tests (\*.test.ts files and the .spec.ts files marked a vscode-mock friendly) +- `yarn test:e2e` - Run only integration tests (\*.spec.ts files) +- `yarn lint` - Run linting +- `yarn test-reset-workspace` to clean test workspace + +Unit tests run in Node.js environment using Jest +Integration tests require VS Code extension host + +While in development we mostly want to use `yarn test:unit-with-specs`. +When multiple tests are failing, look at all of them, but only focus on fixing the first one. Once that is fixed, run the test suite again and repeat the process. + +When writing tests keep mocking to a bare minimum. Code should be written in a way that is easily testable and if I/O is necessary, it should be done in appropriate temporary directories. +Never mock anything that is inside `packages/foam-vscode/src/core/`. + +Use the utility functions from `test-utils.ts` and `test-utils-vscode.ts` and `test-datastore.ts`. + +To improve readability of the tests, set up the test and tear it down within the test case (as opposed to use other functions like `beforeEach` unless it's much better to do it that way) + +## Repository Structure + +This is a monorepo using Yarn workspaces with the main VS Code extension in `packages/foam-vscode/`. + +### Key Directories + +- `packages/foam-vscode/src/core/` - Platform-agnostic business logic (NO vscode dependencies) +- `packages/foam-vscode/src/features/` - VS Code-specific features and UI +- `packages/foam-vscode/src/services/` - service implementations, might have VS Code dependency, but we try keep that to a minimum +- `packages/foam-vscode/src/test/` - Test utilities and mocks +- `docs/` - Documentation and user guides + +### Important Constraint + +Code in `packages/foam-vscode/src/core/` MUST NOT depend on the `vscode` library or any files outside the core directory. This maintains platform independence. + +## Architecture Overview + +### Core Abstractions + +**FoamWorkspace** - Central repository managing all resources (notes, attachments) + +- Uses reversed trie for efficient resource lookup +- Event-driven updates (onDidAdd, onDidUpdate, onDidDelete) +- Handles identifier resolution for short-form linking + +**FoamGraph** - Manages relationship graph between resources + +- Tracks links and backlinks between resources +- Real-time updates when workspace changes +- Handles placeholder resources for broken links + +**ResourceProvider Pattern** - Pluggable architecture for different file types + +- `MarkdownProvider` for .md files +- `AttachmentProvider` for other file types +- Extensible for future resource types + +**DataStore Interface** - Abstract file system operations + +- Platform-agnostic file access with configurable filtering +- Supports both local and remote file systems + +### Feature Integration Pattern + +Features are registered as functions receiving: + +```typescript +(context: ExtensionContext, foamPromise: Promise) => void +``` + +This allows features to: + +- Register VS Code commands, providers, and event handlers +- Access the Foam workspace when ready +- Extend markdown-it for preview rendering + +### Testing Conventions + +- `*.test.ts` - Unit tests using Jest +- `*.spec.ts` - Integration tests requiring VS Code extension host +- Tests live alongside source code in `src/` +- Test cases should be phrased in terms of aspects of the feature being tested (expected behaviors), as they serve both as validation of the code as well as documentation of what the expected behavior for the code is in different situations. They should include the happy paths and edge cases. + +## Development Workflow + +- Whenever working on a feature or issue, let's always come up with a plan first, then save it to a file called `/.agent/current-plan.md`, before getting started with code changes. Update this file as the work progresses. +- Let's use pure functions where possible to improve readability and testing. +- After saving a file, always run `prettier` on it to adjust its formatting. + +### Adding New Features + +1. Create feature in `src/features/` directory +2. Register feature in `src/features/index.ts` +3. Add tests (both unit and integration as needed) +4. Update configuration in `package.json` if needed + +### Working on an issue + +1. Get the issue information from github +2. Define a step by step plan for addressing the issue +3. Create tests for the feature +4. Starting from the first test case, implement the feature so the test passes + +### Core Logic Changes + +1. Modify code in `src/core/` (ensure no vscode dependencies) +2. Add comprehensive unit tests +3. Update integration tests in features that use the core logic + +## Configuration + +The extension uses VS Code's configuration system with the `foam.*` namespace. +You can find all the settings in `/packages/foam-vscode/package.json` + +## Common Development Tasks + +### Extending Core Functionality + +When adding to `src/core/`: + +- Keep platform-agnostic (no vscode imports) +- Add comprehensive unit tests +- Consider impact on graph and workspace state +- Update relevant providers if needed + +## Dependencies + +- **Runtime**: VS Code API, markdown parsing, file watching +- **Development**: TypeScript, Jest, ESLint, esbuild +- **Key Libraries**: remark (markdown parsing), lru-cache, lodash + +The extension supports both Node.js and browser environments via separate build targets. + +# GitHub CLI Integration + +To interact with the github repo we will be using the `gh` command. +ALWAYS ask before performing a write operation on Github. + +## Common Commands for Claude Code Integration + +### Issues + +```bash +# List all issues +gh issue list + +# Filter issues by milestone +gh issue list --milestone "v1.0.0" + +# Filter issues by assignee +gh issue list --assignee @me +gh issue list --assignee username + +# Filter issues by label +gh issue list --label "bug" +gh issue list --label "enhancement,priority-high" + +# Filter issues by state +gh issue list --state open +gh issue list --state closed +gh issue list --state all + +# Combine filters +gh issue list --milestone "v1.0.0" --label "bug" --assignee @me + +# View specific issue +gh issue view 123 + +# Create issue +gh issue create --title "Bug fix" --body "Description" + +# Add comment to issue +gh issue comment 123 --body "Update comment" +``` + +### Pull Requests + +```bash +# List all PRs +gh pr list + +# Filter PRs the same way as for filters (for example, here is by milestone) +gh pr list --milestone "v1.0.0" + +# View PR details +gh pr view 456 + +# Create PR +gh pr create --title "Feature" --body "Description" + +# Check out PR locally +gh pr checkout 456 + +# Add review comment +gh pr comment 456 --body "LGTM" +``` diff --git a/docs/dev/contribution-guide.md b/docs/dev/contribution-guide.md index 79fa2d04d..e98a83412 100644 --- a/docs/dev/contribution-guide.md +++ b/docs/dev/contribution-guide.md @@ -26,7 +26,8 @@ Finally, the easiest way to help, is to use it and provide feedback by [submitti ## Contributing -If you're interested in contributing, this short guide will help you get things set up locally (assuming [node.js >= v16](https://nodejs.org/) and [yarn](https://yarnpkg.com/) are already installed on your system). +If you're interested in contributing, this short guide will help you get things set up locally (assuming [node.js >= v18](https://nodejs.org/) and [yarn](https://yarnpkg.com/) are already installed on your system). +You can also use the provided [[devcontainers]] to avoid installing dependencies locally. With the Dev Containers extension installed, open the repository in VS Code and run **Dev Containers: Reopen in Container**. 1. Fork the project to your Github account by clicking the "Fork" button on the top right hand corner of the project's [home repository page](https://github.com/foambubble/foam). 2. Clone your newly forked repo locally: @@ -86,7 +87,7 @@ This guide assumes you read the previous instructions and you're set up to work 1. Now we'll use the launch configuration defined at [`.vscode/launch.json`](https://github.com/foambubble/foam/blob/main/.vscode/launch.json) to start a new extension host of VS Code. Open the "Run and Debug" Activity (the icon with the bug on the far left) and select "Run VSCode Extension" in the pop-up menu. Now hit F5 or click the green arrow "play" button to fire up a new copy of VS Code with your extension installed. -2. In the new extension host of VS Code that launched, open a Foam workspace (e.g. your personal one, or a test-specific one created from [foam-template](https://github.com/foambubble/foam-template)). This is strictly not necessary, but the extension won't auto-run unless it's in a workspace with a `.vscode/foam.json` file. +2. In the new extension host of VS Code that launched, open a Foam workspace (e.g. your personal one, or a test-specific one created from [foam-template](https://github.com/foambubble/foam-template)). 3. Test a command to make sure it's working as expected. Open the Command Palette (Ctrl/Cmd + Shift + P) and select "Foam: Update Markdown Reference List". If you see no errors, it's good to go! @@ -111,6 +112,7 @@ 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" +[devcontainers]: devcontainers.md "Using Dev Containers" [recipes]: ../user/recipes/recipes.md "Recipes" [recommended-extensions]: ../user/getting-started/recommended-extensions.md "Recommended Extensions" [//end]: # "Autogenerated link references" diff --git a/docs/dev/devcontainers.md b/docs/dev/devcontainers.md new file mode 100644 index 000000000..9f13e6e77 --- /dev/null +++ b/docs/dev/devcontainers.md @@ -0,0 +1,13 @@ +# Using Dev Containers + +Foam provides a [devcontainer](https://devcontainer.ai/) configuration to make it easy to contribute without installing Node and Yarn locally. + +## Quick start + +1. Install [VS Code](https://code.visualstudio.com/) and the [Dev Containers](https://aka.ms/vscode-remote/download/extension) extension. +2. Open the Foam repository in VS Code. +3. Run **Dev Containers: Reopen in Container** from the command palette. + +This will build a Docker image with Node 18 and install dependencies using `yarn install`. Once ready you can run the usual build and test commands from the integrated terminal. + + diff --git a/docs/dev/proposals/templates-v2.md b/docs/dev/proposals/templates-v2.md deleted file mode 100644 index e5d7ddbff..000000000 --- a/docs/dev/proposals/templates-v2.md +++ /dev/null @@ -1,329 +0,0 @@ -# Templates v2 Proposal - -The current capabilities of templates is limited in some important ways. This document aims to propose a design that addresses these shortcomings. - -**IMPORTANT: This design is merely a proposal of a design that could be implemented. It DOES NOT represent a commitment by `Foam` developers to implement the features outlined in this document. This document is merely a mechanism to facilitate discussion of a possible future direction for `Foam`.** - -- [Introduction](#introduction) -- [Limitations of current templating](#limitations-of-current-templating) - - [Too much friction to create a new note](#too-much-friction-to-create-a-new-note) - - [Manual note creation (Mouse + Keyboard)](#manual-note-creation-mouse--keyboard) - - [Manual note creation (Keyboard)](#manual-note-creation-keyboard) - - [Foam missing note creation](#foam-missing-note-creation) - - [`Markdown Notes: New Note` (Keyboard)](#markdown-notes-new-note-keyboard) - - [Foam template note creation (Keyboard)](#foam-template-note-creation-keyboard) - - [Templating of daily notes](#templating-of-daily-notes) - - [Templating of filepaths](#templating-of-filepaths) -- [Goal / Philosophy](#goal--philosophy) -- [Proposal](#proposal) - - [Summary](#summary) - - [Add a `${title}` and `${titleSlug}` template variables](#add-a-title-and-titleslug-template-variables) - - [Add a `Foam: Create New Note` command and hotkey](#add-a-foam-create-new-note-command-and-hotkey) - - [Case 1: `.foam/templates/new-note.md` doesn't exist](#case-1-foamtemplatesnew-notemd-doesnt-exist) - - [Case 2: `.foam/templates/new-note.md` exists](#case-2-foamtemplatesnew-notemd-exists) - - [Change missing wikilinks to use the default template](#change-missing-wikilinks-to-use-the-default-template) - - [Add a metadata section to templates](#add-a-metadata-section-to-templates) - - [Example](#example) - - [Add a replacement for `dateFormat`](#add-a-replacement-for-dateformat) - - [Add support for daily note templates](#add-support-for-daily-note-templates) - - [Eliminate all `foam.openDailyNote` settings](#eliminate-all-foamopendailynote-settings) -- [Summary: resulting behaviour](#summary-resulting-behaviour) - - [`Foam: Create New Note`](#foam-create-new-note) - - [`Foam: Open Daily Note`](#foam-open-daily-note) - - [Navigating to missing wikilinks](#navigating-to-missing-wikilinks) - - [`Foam: Create Note From Template`](#foam-create-note-from-template) -- [Extensions](#extensions) - - [More variables in templates](#more-variables-in-templates) - - [`defaultFilepath`](#defaultfilepath) - - [Arbitrary hotkey -> template mappings?](#arbitrary-hotkey---template-mappings) - -## Introduction - -Creating of new notes in Foam is too cumbersome and slow. Despite their power, Foam templates can currently only be used in very limited scenarios. - -This proposal aims to address these issues by streamlining note creation and by allowing templates to be used everywhere. - -## Limitations of current templating - -### Too much friction to create a new note - -Creating new notes should an incredibly streamlined operation. There should be no friction to creating new notes. - -Unfortunately, all of the current methods for creating notes are cumbersome. - -#### Manual note creation (Mouse + Keyboard) - -1. Navigate to the directory where you want the note -2. Click the new file button -3. Provide a filename -4. Manually enter the template contents you want - -#### Manual note creation (Keyboard) - -1. Navigate to the directory where you want the note -2. `⌘N` to create a new file -3. `⌘S` to save the file and give it a filename -4. Manually enter the template contents you want - -#### Foam missing note creation - -1. Open an existing note in the directory where you want the note -2. Use the wikilinks syntax to create a link to the title of the note you want to have -3. Use `Ctrl+Click`/`F12` to create the new file -4. Manually enter the template contents you want - -#### `Markdown Notes: New Note` (Keyboard) - -1. Navigate to the directory where you want the note -2. `Shift+⌘P` to open the command palette -3. Type `New Note` until it appears in the list. Press `Enter/Return` to select it. -4. Enter a title for the note -5. Manually enter the template contents you want - -#### Foam template note creation (Keyboard) - -1. `Shift+⌘P` to open the command palette -2. Type `Create New Note From Template` until it appears in the list. Press `Enter/Return` to select it. -3. Use the arrow keys (or type the template name) to select the template. Press `Enter/Return` to select it. -4. Modify the filepath to match the desired directory + filename. Press `Enter/Return` to select it. - -All of these steps are far too cumbersome. And only the last one allows the use of templates. - -### Templating of daily notes - -Currently `Open Daily Note` opens an otherwise empty note, with a title defined by the `foam.openDailyNote.titleFormat` setting. -Daily notes should be able to be fully templated as well. - -### Templating of filepaths - -As discussed in ["Template the filepath in `openDailyNote`"](https://github.com/foambubble/foam/issues/523), it would be useful to be able to specify the default filepaths of templates. For example, many people include timestamps in their filepaths. - -## Goal / Philosophy - -In a sentence: **Creating a new note should be a single button press and should use templates.** - -## Proposal - -1. Add a new `Foam: Create New Note` that is the streamlined counterpart to the more flexible `Foam: Create New Note From Template` -2. Use templates everywhere -3. Add metadata into the actual templates themselves in order to template the filepaths themselves. - -### Summary - -This can be done through a series of changes to the way that templates are implemented: - -1. Add a `${title}` and `${titleSlug}` template variables -2. Add a `Foam: Create New Note` command and hotkey -3. Change missing wikilinks to use the default template -4. Add a metadata section to templates -5. Add a replacement for `dateFormat` -6. Add support for daily note templates -7. Eliminate all `foam.openDailyNote` settings - -I've broken it out into these steps to show that the overall proposal can be implemented piecemeal in independent PRs that build on one another. - -### Add a `${title}` and `${titleSlug}` template variables - -When you use `Markdown Notes: New Note`, and give it a title, the title is formatted as a filename and also used as the title in the resulting note. - -**Example:** - -Given the title `Living in a dream world` to `Markdown Notes: New Note`, the filename is `living-in-a-dream-world.md` and the file contents are: - -```markdown -# Living in a dream world -``` - -When creating a note from a template in Foam, you should be able to use a `${title}` variable. If the template uses the `${title}` variable, the user will be prompted for a title when they create a note from a template. - -Example: - -Given this `.foam/templates/my_template.md` template that uses the `${title}` variable: - -```markdown -# ${title} -``` - -When a user asks for a new note using this template (eg. `Foam: Create New Note From Template`), VSCode will first ask the user for a title then provide it to the template, producing: - -```markdown -# Living in a dream world -``` - -There will also be a `${titleSlug}` variable made available, which will be the "slugified" version of the title (eg. `living-in-a-dream-world`). This will be useful in later steps where we want to template the filepath of a template. - -### Add a `Foam: Create New Note` command and hotkey - -Instead of using `Markdown Notes: New Note`, Foam itself will have a `Create New Note` command that creates notes using templates. - -This would open use the template found at `.foam/templates/new-note.md` to create the new note. - -`Foam: Create New Note` will offer the fastest workflow for creating a note when you don't need customization, while `Foam: Create New Note From Template` will remain to serve a fully customizable (but slower) workflow. - -#### Case 1: `.foam/templates/new-note.md` doesn't exist - -If `.foam/templates/new-note.md` doesn't exist, it behaves the same as `Markdown Notes: New Note`: - -* it would ask for a title and create the note in the current directory. It would open a note with the note containing the title. - -**Note:** this would use an implicit default template, making use of the `${title}` variable. - -#### Case 2: `.foam/templates/new-note.md` exists - -If `.foam/templates/new-note.md` exists: - -* it asks for the note title and creates the note in the current directory - -**Progress:** At this point, we have a faster way to create new notes from templates. - -### Change missing wikilinks to use the default template - -Clicking on a dangling/missing wikilink should be equivalent to calling `Foam: Create New Note` with the contents of the link as the title. -That way, creating a note by navigating to a missing note uses the default template. - -### Add a metadata section to templates - -* The `Foam: New Note` command creates a new note in the current directory. This is a sensible default that makes it quick, but lacks flexibility. -* The `Foam: Create New Note From Template` asks the user to confirm/customize the filepath. This is more flexible but slower since there are more steps involved. - -Both commands use templates. It would be nice if we could template the filepaths as well as the template contents (See ["Template the filepath in `openDailyNote`"](https://github.com/foambubble/foam/issues/523) for a more in-depth discussion the benefits of filepath templating). - -In order to template the filepath, there needs to be a place where metadata like this can be specified. -I think this metadata should be stored alongside the templates themselves. That way, it can make use of all the same template variable available to the templates themselves. - -Conceptually, adding metadata to the templates is similar to Markdown frontmatter, though the choice of exact syntax for adding this metadata will have to be done with care since the templates can contain arbitrary contents including frontmatter. - -#### Example - -A workable syntax is still to be determined. -While this syntax probably doesn't work as a solution, for this example I will demonstrate the concept using a second frontmatter block: - -```markdown - - ---- - - - -filepath: `journal/${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE}_${titleSlug}.md` ---- - - ---- ---- -created: ${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE}T${CURRENT_HOUR}:${CURRENT_MINUTE}:${CURRENT_SECOND} -tags: [] ---- - -# ${title} -``` - -In this example, using this template improves the UX: - -In `Foam: Create New Note` workflow, having `filepath` metadata within `.foam/templates/new-note.md` allows for control over the filepath without having to introduce any more UX steps to create a new note. It's still just a hotkey away and a title. - -As we'll see, when it comes to allowing daily notes to be templated, we don't even need to use `${title}` in our template, in which case we don't we don't even need to prompt for a title. - -In the `Create New Note From Template` workflow, during the step where we allow the user to customize the filepath, it will already templated according to the `filepath` in the template's metadata. This means that the user has to make fewer changes to the path, especially in cases where they want to include things like datetimes in the filenames. This makes it faster (eg. don't have to remember what day it is, and don't have to type it) and less error-prone (eg. when they accidentally type the wrong date). - -### Add a replacement for `dateFormat` - -`foam.openDailyNote.filenameFormat` uses `dateFormat()` to put the current timestamp into the daily notes filename. This is much more flexible than what is available in VSCode Snippet variables. Before daily notes are switched over to use templates, we will have to come up with another mechanism/syntax to allow for calls to `dateFormat()` within template files. - -This would be especially useful in the migration of users to the new daily notes templates. For example, if `.foam/templates/daily-note.md` is unset, then we could generate an implicit template for use by `Foam: Open Daily Note`. Very roughly something like: - -```markdown - - ---- - - - -filepath: `${foam.openDailyNote.directory}/${foam.openDailyNote.filenameFormat}.${foam.openDailyNote.fileExtension}` ---- - - ---- -# ${foam.openDailyNote.titleFormat} -``` - -### Add support for daily note templates - -With the above features implemented, making daily notes use templates is simple. - -We define a `.foam/templates/daily-note.md` filepath that the `Foam: Open Daily Note` command will always use to find its daily note template. -If `.foam/templates/daily-note.md` does not exist, it falls back to a default, implicitly defined daily notes template (which follows the default behaviour of the current `foam.openDailyNote` settings). - -Both `Foam: Open Daily Note` and `Foam: Create New Note` can share all of the implementation code, with the only differences being the hotkeys used and the template filepath used. - -Example daily note template (again using the example syntax of the foam-specific frontmatter block): - -```markdown - - ---- - - - -filepath: `journal/${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE}.md` ---- - - ---- -# ${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE} -``` - -Since there is no use of the `${title}` variable, opening the daily note behaves exactly as it does today and automatically opens the note with no further user interaction. - -### Eliminate all `foam.openDailyNote` settings - -Now that all of the functionality of the `foam.openDailyNote` settings have been obviated, these settings can be removed: - -* `foam.openDailyNote.directory`, `foam.openDailyNote.filenameFormat`, and `foam.openDailyNote.fileExtension` can be specified in the `filepath` metadata of the daily note template. -* `foam.openDailyNote.titleFormat` has been replaced by the ability to fully template the daily note, including the title. - -## Summary: resulting behaviour - -### `Foam: Create New Note` - -A new command optimized for speedy creation of new notes. This will become the default way to create new notes. In its fastest form, it simply opens the new note with no further user interaction. - -### `Foam: Open Daily Note` - -Simplified since it no longer has its custom settings, and re-uses all the same implementation code as `Foam: Create New Note`. -Templates can now be used with daily notes. - -### Navigating to missing wikilinks - -Now creates the new notes using the default template. Re-uses all the same implementation code as `Foam: Create New Note` -Now uses the contents of the wikilink as the `${title}` parameter for the template. - -### `Foam: Create Note From Template` - -Almost the exact same as it is today. However, with `${title}` and `filepath` templating, users will have less changes to make in the filepath confirmation step. -It's the slower but more powerful version of `Foam: Create New Note`, allowing you to pick any template, as well as customize the filepath. - -## Extensions - -In addition to the ideas of this proposal, there are ways we could imagine extending it. These are all "out of scope" for this design, but thinking about them could be useful to guide our thinking about this design. - -### More variables in templates - -`${title}` is necessary in this case to replace the functionality of `Markdown Notes: New Note`. -However, one could imagine that this pattern of "Ask the user for a value for missing variable values" could be useful in other situations too. -Perhaps users could even define their own (namespaced) template variables, and Foam would ask them for values to use for each when creating a note using a template that used those variables. - -### `defaultFilepath` - -By using `defaultFilepath` instead of `filepath` in the metadata section, you could have more control over the note creation without having to fall back to the full `Create New Note From Template` workflow. - -* `filepath` will not ask the user for the file path, simply use the value provided (as described above) -* `defaultFilepath` will ask the user for the file path, pre-populating the file path using `defaultFilepath` - -The first allows "one-click" note creation, the second more customization. -This might not be necessary, or this might not be the right way to solve the problem. We'll see. - -### Arbitrary hotkey -> template mappings? - -`Foam: Open Daily Note` and `Foam: Create New Note` only differ by their hotkey and their default template setting. -Is there a reason/opportunity to abstract this further and allow for users to define custom `hotkey -> template` mappings? diff --git a/docs/dev/testing.md b/docs/dev/testing.md new file mode 100644 index 000000000..7940eac12 --- /dev/null +++ b/docs/dev/testing.md @@ -0,0 +1,130 @@ +# Testing in Foam VS Code Extension + +This document explains the testing strategy and conventions used in the Foam VS Code extension. + +## Test File Types + +We use two distinct types of test files, each serving different purposes: + +### `.test.ts` Files - Pure Unit Tests + +- **Purpose**: Test business logic and algorithms in complete isolation +- **Dependencies**: No VS Code APIs dependencies +- **Environment**: Pure Jest with Node.js +- **Speed**: Very fast execution +- **Location**: Throughout the codebase alongside source files + +### `.spec.ts` Files - Integration Tests with VS Code APIs + +- **Purpose**: Test features that integrate with VS Code APIs and user workflows +- **Dependencies**: Will likely depend on VS Code APIs (`vscode` module), otherwise avoid incurring the performance hit +- **Environment**: Can run in TWO environments: + - **Mock Environment**: Jest with VS Code API mocks (fast) + - **Real VS Code**: Full VS Code extension host (slow but comprehensive) +- **Speed**: Depends on environment (see performance section below) +- **Location**: Primarily in `src/features/` and service layers + +## Key Principle: Environment Flexibility for `.spec.ts` Files + +**`.spec.ts` files use VS Code APIs**, but they can run in different environments: + +- **Mock Environment**: Uses our VS Code API mocks for speed +- **Real VS Code**: Uses actual VS Code extension host for full integration testing + +This dual-environment capability allows us to: + +- Run specs quickly during development (mock environment) +- Verify full integration during CI/CD (real VS Code environment) +- Gradually migrate specs to mock-compatible implementations + +## Performance Comparison + +| Test Type | Environment | Typical Duration | VS Code APIs | +| --------------------- | ---------------------- | ---------------- | ---------------- | +| **`.test.ts`** | Pure Jest | fastest | **No** | +| **`.spec.ts` (mock)** | Jest + VS Code Mocks | fast | **Yes** (mocked) | +| **`.spec.ts` (real)** | VS Code Extension Host | sloooooow. | **Yes** (real) | + +## Running Tests + +### Available Commands + +- **`yarn test:unit`**: Runs only `.test.ts` files (no VS Code dependencies) +- **`yarn test:unit-with-specs`**: Runs `.test.ts` + `@unit-ready` marked `.spec.ts` files using mocks +- **`yarn test:e2e`**: Runs all `.spec.ts` files in full VS Code extension host +- **`yarn test`**: Runs both unit and e2e test suites sequentially + +## Mock Environment Migration + +We're gradually enabling `.spec.ts` files to run in our fast mock environment while maintaining their ability to run in real VS Code. + +### The `@unit-ready` Annotation + +Spec files marked with `/* @unit-ready */` can run in both environments: + +```typescript +/* @unit-ready */ +import * as vscode from 'vscode'; +// ... test uses VS Code APIs but works with our mocks +``` + +### Common Migration Fixes + +**Configuration defaults**: Our mocks don't load package.json defaults + +```typescript +// Before +const format = getFoamVsCodeConfig('openDailyNote.filenameFormat'); + +// After (defensive) +const format = getFoamVsCodeConfig( + 'openDailyNote.filenameFormat', + 'yyyy-mm-dd' +); +``` + +**File system operations**: Ensure proper async handling + +```typescript +// Mock file operations are immediate but still async +await vscode.workspace.fs.writeFile(uri, content); +``` + +### When NOT to Migrate + +Some specs should remain real-VS-Code-only: + +- Tests verifying complex VS Code UI interactions +- Tests requiring real file system watching with timing +- Tests validating extension packaging or activation +- Tests that depend on VS Code's complex internal state management + +## Mock System Capabilities + +Our `vscode-mock.ts` provides comprehensive VS Code API mocking: + +## Contributing Guidelines + +When adding new tests: + +1. **Choose the right type**: + + - Use `.test.ts` for pure business logic with no VS Code dependencies + - Use `.spec.ts` for anything that needs VS Code APIs + +2. **Consider mock compatibility**: + + - When writing `.spec.ts` files, consider if they could run in mock environment + - Add `/* @unit-ready */` if the test works with our mocks + +3. **Follow naming conventions**: + + - Test files should be co-located with source files when possible + - Use descriptive test names that explain the expected behavior + +4. **Performance awareness**: + - Prefer unit tests for business logic (fastest) + - Use mock-compatible specs for VS Code integration (fast) + - Reserve real VS Code specs for complex integration scenarios (comprehensive) + +This testing strategy gives us the best of both worlds: fast feedback during development and comprehensive integration verification when needed. diff --git a/docs/user/features/note-templates.md b/docs/user/features/note-templates.md index 006fb902c..453223bc0 100644 --- a/docs/user/features/note-templates.md +++ b/docs/user/features/note-templates.md @@ -2,45 +2,56 @@ Foam supports note templates which let you customize the starting content of your notes instead of always starting from an empty note. -Note templates are `.md` files located in the special `.foam/templates` directory of your workspace. +Foam supports two types of templates: + +- **Markdown templates** (`.md` files) - Simple templates with predefined content and variables +- **JavaScript templates** (`.js` files) - Smart templates that can adapt based on context and make intelligent decisions + +Both types of templates are located in the special `.foam/templates` directory of your workspace. ## Quickstart -Create a template: +### Creating templates + +**For simple templates:** - Run the `Foam: Create New Template` command from the command palette - OR manually create a regular `.md` file in the `.foam/templates` directory +**For smart templates:** + +- Create a `.js` file in the `.foam/templates` directory (see [JavaScript Templates](#javascript-templates) section below) + ![Create new template GIF](../../assets/images/create-new-template.gif) -_Theme: Ayu Light_ +### Using templates To create a note from a template: -- Run the `Foam: Create New Note From Template` command and follow the instructions. Don't worry if you've not created a template yet! You'll be prompted to create a new template if none exist. -- OR run the `Foam: Create New Note` command, which uses the special default template (`.foam/templates/new-note.md`, if it exists) +- Run the `Foam: Create New Note From Template` command and follow the instructions. Don't worry if you've not created a template yet! You'll be prompted to create a new simple template if none exist. +- OR run the `Foam: Create New Note` command, which uses the special default template (`.foam/templates/new-note.md` or `.foam/templates/new-note.js`, if it exists) ![Create new note from template GIF](../../assets/images/create-new-note-from-template.gif) -_Theme: Ayu Light_ - ## Special templates ### Default template -The `.foam/templates/new-note.md` template is special in that it is the template that will be used by the `Foam: Create New Note` command. -Customize this template to contain content that you want included every time you create a note. To begin it is _recommended_ to define the YAML Front-Matter of the template similar to the following: +The default template is used by the `Foam: Create New Note` command. Foam will look for these templates in order: -```markdown ---- -type: basic-note ---- -``` +1. `.foam/templates/new-note.js` (JavaScript template) +2. `.foam/templates/new-note.md` (Markdown template) + +Customize this template to contain content that you want included every time you create a note. ### Default daily note template -The `.foam/templates/daily-note.md` template is special in that it is the template that will be used when creating daily notes (e.g. by using `Foam: Open Daily Note`). -Customize this template to contain content that you want included every time you create a daily note. To begin it is _recommended_ to define the YAML Front-Matter of the template similar to the following: +The daily note template is used when creating daily notes (e.g. by using `Foam: Open Daily Note`). Foam will look for these templates in order: + +1. `.foam/templates/daily-note.js` (JavaScript template) +2. `.foam/templates/daily-note.md` (Markdown template) + +For a simple markdown template, it is _recommended_ to define the YAML Front-Matter similar to the following: ```markdown --- @@ -48,9 +59,184 @@ type: daily-note --- ``` -## Variables +## JavaScript Templates + +JavaScript templates are a powerful way to create smart, context-aware note templates that can adapt based on the situation. Unlike static Markdown templates, JavaScript templates can make intelligent decisions about what content to include. + +**Use JavaScript templates when you want to:** + +- Create different note structures based on the day of the week, time, or date +- Adapt templates based on where the note is being created from +- Automatically find and link related notes in your workspace +- Generate content based on existing notes or workspace structure +- Implement complex logic that static templates cannot handle + +### Basic JavaScript template structure + +A JavaScript template is a `.js` file that exports a function returning note content, and optionally location: + +```javascript +// .foam/templates/daily-note.js +async function createNote({ trigger, foam, resolver, foamDate }) { + const today = dayjs(); + // or you could use foamDate for day specific notes, see FOAM_DATE_* variables + // const day = dayjs(foamDate) + const formattedDay = today.format('YYYY-MM-DD'); + + // if you need a variable you can use the resolver + // const title = await resolver.resolveFromName('FOAM_TITLE'); + + console.log( + 'Creating note for today: ' + formattedDay, + JSON.stringify(trigger) + ); + + let content = `# Daily Note - ${formattedDay} + +## Today's focus +- + +## Notes +- +`; + + switch (today.day()) { + case 1: // Monday + content = `# Week Planning - ${formattedDay} + +## This week's goals +- [ ] Goal 1 +- [ ] Goal 2 + +## Focus areas +- +`; + break; + case 5: // Friday + content = `# Week Review - ${formattedDay} + +## What went well +- + +## What could be improved +- + +## Next week's priorities +- +`; + break; + } + + return { + content, + filepath: `/weekly-planning/${formattedDay}.md`, + }; +} +``` + +### Examples + +**Smart meeting notes:** + +```javascript +async function createNote({ trigger, foam, resolver }) { + const title = (await resolver.resolveFromName('FOAM_TITLE')) || 'Meeting'; + const today = dayjs(); + // Detect meeting type from title + const isStandup = title.toLowerCase().includes('standup'); + const isReview = title.toLowerCase().includes('review'); + + let template = `# ${title} - ${today.format('YYYY-MM-DD')} + +`; + + if (isStandup) { + template += `## What I did yesterday +- + +## What I'm doing today +- + +## Blockers +- +`; + } else if (isReview) { + template += `## What went well +- + +## What could be improved +- + +## Action items +- [ ] +`; + } else { + template += `## Agenda +- + +## Notes +- + +## Action items +- [ ] +`; + } + + return { + content: template, + filepath: `/meetings/${title}.md`, + }; +} +``` + +### Template result format + +JavaScript templates must return an object with: + +- `content` (required): The note content as a string +- `filepath` (required): Custom file path for the note + - NOTE: the path must be within the workspace. + - A relative path will be resolved based on the `onRelativePath` command configuration. + - An absolute path will be taken as is, if it falls within the workspace. Otherwise it will be considered to be from the workspace root + +```javascript +return { + content: '# My Note\n\nContent here...', + filepath: 'custom-folder/my-note.md', +}; +``` + +### Security and limitations + +JavaScript templates run in a best-effort secured environment: + +- ✅ Can only run from trusted VS Code workspaces +- ✅ Can access Foam workspace and utilities +- ✅ Can use standard JavaScript features +- ✅ Have a 30-second execution timeout +- ❌ Cannot access the file system directly +- ❌ Cannot make network requests +- ❌ Cannot access Node.js modules -Templates can use all the variables available in [VS Code Snippets](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_variables). +This increases the chances that templates stay safe while still being powerful enough for complex logic. + +STILL - PLEASE BE AWARE YOU ARE EXECUTING CODE ON YOUR MACHINE. THIS SANDBOX IS NOT MEANT TO BE THE ULTIMATE SECURITY SOLUTION. + +**YOU MUST TRUST THE REPO CONTRIBUTORS** + +## Markdown templates + +Markdown templates are a simple way to create notes + +**Use Markdown templates when you want to:** + +- Create simple, consistent note structures +- Use basic variables and placeholders +- Keep templates easy to read and modify + +### Variables + +Markdown templates can use all the variables available in [VS Code Snippets](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_variables). In addition, you can also use variables provided by Foam: @@ -93,9 +279,9 @@ If instead you were to use the VS Code versions of these variables, they would b 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 +### Metadata -Templates can also contain metadata about the templates themselves. The metadata is defined in YAML "Frontmatter" blocks within the templates. +**Markdown templates** can also contain metadata about the templates themselves. The metadata is defined in YAML "Frontmatter" blocks within the templates. | Name | Description | | ------------- | -------------------------------------------------------------------------------------------------------------------------------- | @@ -105,40 +291,7 @@ Templates can also contain metadata about the templates themselves. The metadata Foam-specific variables (e.g. `$FOAM_TITLE`) can be used within template metadata. However, VS Code snippet variables are ([currently](https://github.com/foambubble/foam/pull/655)) not supported. -### `filepath` attribute - -The `filepath` metadata attribute allows you to define a relative or absolute filepath to use when creating a note using the template. If the filepath is a relative filepath, it is relative to the current workspace. - -#### Example of **relative** `filepath` - -For example, `filepath` can be used to customize `.foam/templates/new-note.md`, overriding the default `Foam: Create New Note` behaviour of opening the file in the same directory as the active file: - -```yaml ---- -# This will create the note in the "journal" subdirectory of the current workspace, -# regardless of which file is the active file. -foam_template: - filepath: 'journal/$FOAM_TITLE.md' ---- -``` - -#### Example of **absolute** `filepath` - -`filepath` can be an absolute filepath, so that the notes get created in the same location, regardless of which file or workspace the editor currently has open. -The format of an absolute filepath may vary depending on the filesystem used. - -```yaml ---- -foam_template: - # Unix / MacOS filesystems - filepath: '/Users/john.smith/foam/journal/$FOAM_TITLE.md' - - # Windows filesystems - filepath: 'C:\Users\john.smith\Documents\foam\journal\$FOAM_TITLE.md' ---- -``` - -#### Example of **date-based** `filepath` +#### `filepath` attribute It is possible to vary the `filepath` value based on the current date using the `FOAM_DATE_*` variables. This is especially useful for the [[daily-notes]] template if you wish to organize by years, months, etc. Below is an example of a daily-note template metadata section that will create new daily notes under the `journal/YEAR/MONTH-MONTH_NAME/` filepath. For example, when a note is created on November 15, 2022, a new file will be created at `C:\Users\foam_user\foam_notes\journal\2022\11-Nov\2022-11-15-daily-note.md`. This method also respects the creation of daily notes relative to the current date (i.e. `/+1d`). @@ -146,27 +299,23 @@ It is possible to vary the `filepath` value based on the current date using the --- type: daily-note foam_template: - description: Daily Note for $FOAM_TITLE - filepath: "C:\\Users\\foam_user\\foam_notes\\journal\\$FOAM_DATE_YEAR\\$FOAM_DATE_MONTH-$FOAM_DATE_MONTH_NAME_SHORT\\$FOAM_DATE_YEAR-$FOAM_DATE_MONTH-$FOAM_DATE_DATE-daily-note.md" + description: Daily Note + filepath: '/journal/$FOAM_DATE_YEAR/$FOAM_DATE_MONTH-$FOAM_DATE_MONTH_NAME_SHORT/$FOAM_DATE_YEAR-$FOAM_DATE_MONTH-$FOAM_DATE_DATE-daily-note.md' --- # $FOAM_DATE_YEAR-$FOAM_DATE_MONTH-$FOAM_DATE_DATE Daily Notes ``` -> Note: this method **requires** the use of absolute file paths, and in this example is using Windows path conventions. This method will also override any filename formatting defined in `.vscode/settings.json` - -### `name` and `description` attributes +#### `name` and `description` attributes These attributes provide a human readable name and description to be shown in the template picker (e.g. When a user uses the `Foam: Create New Note From Template` command): ![Template Picker annotated with attributes](../../assets/images/template-picker-annotated.png) -### Adding template metadata to an existing YAML Frontmatter block +#### Adding template metadata to an existing YAML Frontmatter block If your template already has a YAML Frontmatter block, you can add the Foam template metadata to it. -#### Limitations - Foam only supports adding the template metadata to _YAML_ Frontmatter blocks. If the existing Frontmatter block uses some other format (e.g. JSON), you will have to add the template metadata to its own YAML Frontmatter block. Further, the template metadata must be provided as a [YAML block mapping](https://yaml.org/spec/1.2/spec.html#id2798057), with the attributes placed on the lines immediately following the `foam_template` line: @@ -182,11 +331,7 @@ foam_template: # this is a YAML "Block" mapping ("Flow" mappings aren't supporte This is the rest of the template ``` -Due to the technical limitations of parsing the complex YAML format, unless the metadata is provided this specific form, Foam is unable to correctly remove the template metadata before creating the resulting note. - -If this limitation proves inconvenient to you, please let us know. We may be able to extend our parsing capabilities to cover your use case. In the meantime, you can add the template metadata without this limitation by providing it in its own YAML Frontmatter block. - -### Adding template metadata to its own YAML Frontmatter block +#### Adding template metadata to its own YAML Frontmatter block You can add the template metadata to its own YAML Frontmatter block at the start of the template: diff --git a/lerna.json b/lerna.json index d10edf0a9..e06be8bbe 100644 --- a/lerna.json +++ b/lerna.json @@ -4,5 +4,5 @@ ], "npmClient": "yarn", "useWorkspaces": true, - "version": "0.26.12" + "version": "0.27.2" } diff --git a/package.json b/package.json index 5e72cf6fd..eb3e1b933 100644 --- a/package.json +++ b/package.json @@ -16,9 +16,9 @@ "reset": "yarn && yarn clean && yarn build", "clean": "lerna run clean", "build": "lerna run build", - "test": "yarn workspace foam-vscode test --stream", + "test": "yarn workspace foam-vscode test", "lint": "lerna run lint", - "watch": "lerna run watch --concurrency 20 --stream" + "watch": "lerna run watch --concurrency 20" }, "devDependencies": { "all-contributors-cli": "^6.16.1", diff --git a/packages/foam-vscode/CHANGELOG.md b/packages/foam-vscode/CHANGELOG.md index 5102ed019..32c42dad4 100644 --- a/packages/foam-vscode/CHANGELOG.md +++ b/packages/foam-vscode/CHANGELOG.md @@ -4,6 +4,22 @@ 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.27.1] - 2025-07-24 + +Fixes and Improvements: + +- Fixed handling of daily note template on Windows machines (#1492) + +## [0.27.0] - 2025-07-23 + +Features: + +- Introduced a unified note creation engine supporting both Markdown and JavaScript templates + +Internal: + +- Improved testing framework by creating a mocked VS Code environment + ## [0.26.12] - 2025-06-18 Fixes and Improvements: diff --git a/packages/foam-vscode/jest.config.js b/packages/foam-vscode/jest.config.js index 7febf5896..aeda284bb 100644 --- a/packages/foam-vscode/jest.config.js +++ b/packages/foam-vscode/jest.config.js @@ -123,7 +123,7 @@ module.exports = { // runner: "jest-runner", // The paths to modules that run some code to configure or set up the testing environment before each test - // setupFiles: [], + setupFiles: ['/src/test/support/jest-setup.ts'], // A list of paths to modules that run some code to configure or set up the testing framework before each test setupFilesAfterEnv: ['jest-extended'], @@ -153,9 +153,8 @@ module.exports = { // The regexp pattern or array of patterns that Jest uses to detect test files // This is overridden in every runCLI invocation but it's here as the default - // for vscode-jest. We only want unit tests in the test explorer (sidebar), - // since spec tests require the entire extension host to be launched before. - testRegex: ['\\.test\\.ts$'], + // for vscode-jest. Both .test.ts and .spec.ts files use the vscode-mock. + testRegex: ['\\.(test|spec)\\.ts$'], // This option allows the use of a custom results processor // testResultsProcessor: undefined, diff --git a/packages/foam-vscode/package.json b/packages/foam-vscode/package.json index 7b46d5019..0bec1afe4 100644 --- a/packages/foam-vscode/package.json +++ b/packages/foam-vscode/package.json @@ -8,7 +8,7 @@ "type": "git" }, "homepage": "https://github.com/foambubble/foam", - "version": "0.26.12", + "version": "0.27.2", "license": "MIT", "publisher": "foam", "engines": { @@ -18,9 +18,6 @@ "categories": [ "Other" ], - "activationEvents": [ - "workspaceContains:.vscode/foam.json" - ], "main": "./out/bundles/extension-node.js", "browser": "./out/bundles/extension-web.js", "capabilities": { @@ -678,13 +675,14 @@ "test-reset-workspace": "rm -rf .test-workspace && mkdir .test-workspace && touch .test-workspace/.keep", "test-setup": "yarn compile && yarn build && yarn test-reset-workspace", "test": "yarn test-setup && node ./out/test/run-tests.js", - "test:unit": "yarn test-setup && node ./out/test/run-tests.js --unit", + "test:unit": "yarn test-setup && node ./out/test/run-tests.js --unit --exclude-specs", + "test:unit-with-specs": "yarn test-setup && node ./out/test/run-tests.js --unit", "test:e2e": "yarn test-setup && node ./out/test/run-tests.js --e2e", "lint": "dts lint src", "clean": "rimraf out", "watch": "nodemon --watch 'src/**/*.ts' --exec 'yarn build' --ext ts", "vscode:start-debugging": "yarn clean && yarn watch", - "package-extension": "npx vsce package --yarn", + "package-extension": "npx @vscode/vsce@3.6.0 package --yarn", "install-extension": "code --install-extension ./foam-vscode-$npm_package_version.vsix", "open-in-browser": "vscode-test-web --quality=stable --browser=chromium --extensionDevelopmentPath=. ", "publish-extension-openvsx": "npx ovsx publish foam-vscode-$npm_package_version.vsix -p $OPENVSX_TOKEN", @@ -695,9 +693,8 @@ "@types/dateformat": "^3.0.1", "@types/jest": "^29.5.3", "@types/lodash": "^4.14.157", - "@types/markdown-it": "^12.0.1", "@types/micromatch": "^4.0.1", - "@types/node": "^13.11.0", + "@types/node": "^18.0.0", "@types/picomatch": "^2.2.1", "@types/remove-markdown": "^0.1.1", "@types/vscode": "^1.70.0", @@ -725,7 +722,10 @@ "wait-for-expect": "^3.0.2" }, "dependencies": { + "@types/markdown-it": "^12.0.1", + "@types/unist": "^3.0.3", "dateformat": "4.5.1", + "dayjs": "^1.11.13", "detect-newline": "^3.1.0", "github-slugger": "^1.4.0", "gray-matter": "^4.0.2", diff --git a/packages/foam-vscode/src/core/model/graph.test.ts b/packages/foam-vscode/src/core/model/graph.test.ts index 3deebf030..44bd3b879 100644 --- a/packages/foam-vscode/src/core/model/graph.test.ts +++ b/packages/foam-vscode/src/core/model/graph.test.ts @@ -1,6 +1,14 @@ -import { createTestNote, createTestWorkspace } from '../../test/test-utils'; +import { + createTestNote, + createTestWorkspace, + readFileFromFs, + TEST_DATA_DIR, +} from '../../test/test-utils'; import { FoamGraph } from './graph'; import { URI } from './uri'; +import { createMarkdownParser } from '../services/markdown-parser'; + +const parser = createMarkdownParser([]); describe('Graph', () => { it('should use wikilink slugs to connect nodes', () => { @@ -154,6 +162,52 @@ describe('Graph', () => { expect(graph.getBacklinks(noteB.uri).length).toEqual(1); }); + it('should create inbound connections when targeting a block id', () => { + // Use explicit filenames to avoid async test collisions + const fileA = '/page-a-blockid.md'; + const fileB = '/page-b-blockid.md'; + const noteA = parser.parse( + URI.file(fileA), + 'Link to [[page-b-blockid#^block-1]]' + ); + const noteB = parser.parse( + URI.file(fileB), + 'This is a paragraph with a block identifier. ^block-1' + ); + const ws = createTestWorkspace().set(noteA).set(noteB); + const graph = FoamGraph.fromWorkspace(ws); + + expect(graph.getBacklinks(noteB.uri).map(l => l.source)).toEqual([ + noteA.uri, + ]); + expect(graph.getLinks(noteA.uri).map(l => l.target)).toEqual([ + noteB.uri.with({ fragment: '^block-1' }), + ]); + }); + + it('getBacklinks should report sources of links pointing to a block', () => { + // Use explicit filenames to avoid async test collisions + const fileA = '/page-a-blocklink.md'; + const fileB = '/page-b-blocklink.md'; + const fileC = '/page-c-blocklink.md'; + const noteA = parser.parse( + URI.file(fileA), + '[[page-c-blocklink#^block-1]]' + ); + const noteB = parser.parse( + URI.file(fileB), + '[[page-c-blocklink#^block-1]]' + ); + const noteC = parser.parse(URI.file(fileC), 'some text ^block-1'); + const ws = createTestWorkspace().set(noteA).set(noteB).set(noteC); + const graph = FoamGraph.fromWorkspace(ws); + + const backlinks = graph.getBacklinks(noteC.uri); + expect(backlinks.length).toEqual(2); + const sources = backlinks.map(b => b.source.path).sort(); + expect(sources).toEqual([fileA, fileB]); + }); + it('should support attachments', () => { const noteA = createTestNote({ uri: '/path/to/page-a.md', @@ -455,9 +509,9 @@ describe('Regenerating graph after workspace changes', () => { expect(graph.getLinks(noteA.uri).map(l => l.target)).toEqual([ URI.placeholder('/path/to/another/page-b.md'), ]); - expect(() => - ws.get(URI.placeholder('/path/to/another/page-b.md')) - ).toThrow(); + expect( + graph.contains(URI.placeholder('/path/to/another/page-b.md')) + ).toBeTruthy(); // add note-b const noteB = createTestNote({ @@ -465,7 +519,6 @@ describe('Regenerating graph after workspace changes', () => { }); ws.set(noteB); - FoamGraph.fromWorkspace(ws); expect(() => ws.get(URI.placeholder('page-b'))).toThrow(); expect(ws.get(noteB.uri).type).toEqual('note'); @@ -675,3 +728,52 @@ describe('Updating graph on workspace state', () => { graph.dispose(); }); }); + +describe('Mixed Scenario', () => { + it('should correctly handle a mix of links', async () => { + // Use explicit filenames to avoid async test collisions + const fileTarget = '/mixed-target-async.md'; + const fileOther = '/mixed-other-async.md'; + const fileSource = '/mixed-source-async.md'; + const parser = createMarkdownParser([]); + const ws = createTestWorkspace(); + + const mixedTargetContent = await readFileFromFs( + TEST_DATA_DIR.joinPath('block-identifiers', 'mixed-target.md') + ); + const mixedOtherContent = await readFileFromFs( + TEST_DATA_DIR.joinPath('block-identifiers', 'mixed-other.md') + ); + const mixedSourceContent = await readFileFromFs( + TEST_DATA_DIR.joinPath('block-identifiers', 'mixed-source.md') + ); + + const mixedTarget = parser.parse(URI.file(fileTarget), mixedTargetContent); + const mixedOther = parser.parse(URI.file(fileOther), mixedOtherContent); + const mixedSource = parser.parse(URI.file(fileSource), mixedSourceContent); + + ws.set(mixedTarget).set(mixedOther).set(mixedSource); + const graph = FoamGraph.fromWorkspace(ws); + + const links = graph.getLinks(mixedSource.uri); + // Legacy: placeholder links fallback to slug, not file path + expect(links.map(l => l.target.path).sort()).toEqual([ + 'mixed-target', + 'mixed-target', + 'mixed-target', + 'mixed-target', + 'mixed-target', + 'mixed-target', + ]); + + const backlinks = graph.getBacklinks(mixedTarget.uri); + expect(backlinks.map(b => b.source.path)).toEqual([]); + + const linksFromTarget = graph.getLinks(mixedTarget.uri); + // Legacy: placeholder links fallback to slug, not file path + expect(linksFromTarget.map(l => l.target.path)).toEqual(['mixed-other']); + + const otherBacklinks = graph.getBacklinks(mixedOther.uri); + expect(otherBacklinks.map(b => b.source.path)).toEqual([]); + }); +}); diff --git a/packages/foam-vscode/src/core/model/markdown-parser-block-id.test.ts b/packages/foam-vscode/src/core/model/markdown-parser-block-id.test.ts new file mode 100644 index 000000000..79340234d --- /dev/null +++ b/packages/foam-vscode/src/core/model/markdown-parser-block-id.test.ts @@ -0,0 +1,372 @@ +/* eslint-disable no-console */ +import { URI } from './uri'; +import { Range } from './range'; +import { createMarkdownParser } from '../services/markdown-parser'; +import { Logger } from '../utils/log'; + +Logger.setLevel('error'); + +const parser = createMarkdownParser(); +const parse = (markdown: string) => + parser.parse(URI.parse('test-note.md'), markdown); + +describe('Markdown Parser - Block Identifiers', () => { + describe('Inline Block IDs', () => { + it('should parse a block ID on a simple paragraph', () => { + const markdown = ` +This is a paragraph. ^block-id-1 +`; + const actual = parse(markdown); + expect(actual.sections).toEqual([ + { + id: 'block-id-1', + label: 'This is a paragraph. ^block-id-1', + blockId: '^block-id-1', + type: 'block', + range: Range.create(1, 0, 1, 32), + }, + ]); + }); + + it('should parse a block ID on a heading', () => { + const markdown = ` +## My Heading ^heading-id +`; + const actual = parse(markdown); + expect(actual.sections).toEqual([ + { + id: 'my-heading', + blockId: '^heading-id', + type: 'heading', + label: 'My Heading', + level: 2, // Add level property + range: Range.create(1, 0, 2, 0), + }, + ]); + }); + + it('should parse a block ID on a list item', () => { + const markdown = ` +- List item one ^list-id-1 +`; + const actual = parse(markdown); + expect(actual.sections).toEqual([ + { + id: 'list-id-1', + blockId: '^list-id-1', + type: 'block', + label: '- List item one ^list-id-1', + range: Range.create(1, 0, 1, 26), + }, + ]); + }); + + it('should verify "last one wins" rule for inline block IDs', () => { + const markdown = ` +This is a paragraph. ^first-id ^second-id +`; + const actual = parse(markdown); + expect(actual.sections).toEqual([ + { + id: 'second-id', + blockId: '^second-id', + label: 'This is a paragraph. ^first-id ^second-id', + type: 'block', + range: Range.create(1, 0, 1, 41), + }, + ]); + }); + }); + + describe('Full-line Block IDs', () => { + it('should parse a full-line block ID on a blockquote', () => { + const markdown = ` +> This is a blockquote. +> It can span multiple lines. +^blockquote-id +`; + const actual = parse(markdown); + expect(actual.sections).toEqual([ + { + id: 'blockquote-id', + blockId: '^blockquote-id', + type: 'block', + label: `> This is a blockquote. +> It can span multiple lines.`, + range: Range.create(1, 0, 2, 28), + }, + ]); + }); + + it('should parse a full-line block ID on a code block', () => { + const markdown = ` +\`\`\`typescript +function hello() { + console.log('Hello, world!'); +} +\`\`\` +^code-block-id +`; + const actual = parse(markdown); + expect(actual.sections).toEqual([ + { + id: 'code-block-id', + blockId: '^code-block-id', + type: 'block', + label: `\`\`\`typescript +function hello() { + console.log('Hello, world!'); +} +\`\`\``, + range: Range.create(1, 0, 5, 3), + }, + ]); + }); + + it('should parse a full-line block ID on a table', () => { + const markdown = ` +| Header 1 | Header 2 | +| -------- | -------- | +| Cell 1 | Cell 2 | +| Cell 3 | Cell 4 | +^my-table +`; + const actual = parse(markdown); + expect(actual.sections).toEqual([ + { + id: 'my-table', + blockId: '^my-table', + type: 'block', + label: `| Header 1 | Header 2 | +| -------- | -------- | +| Cell 1 | Cell 2 | +| Cell 3 | Cell 4 |`, + range: Range.create(1, 0, 4, 23), + }, + ]); + }); + + it('should parse a full-line block ID on a list', () => { + const markdown = `- list item 1 +- list item 2 +^list-id`; + const actual = parse(markdown); + expect(actual.sections).toEqual([ + { + id: 'list-id', + blockId: '^list-id', + label: `- list item 1 +- list item 2`, + type: 'block', + range: Range.create(0, 0, 1, 13), + }, + ]); + }); + + it('should verify "last one wins" rule for full-line block IDs', () => { + const markdown = ` +- list item 1 +- list item 2 +^old-list-id ^new-list-id +`; + const actual = parse(markdown); + expect(actual.sections).toEqual([ + { + id: 'new-list-id', + blockId: '^new-list-id', + label: `- list item 1 +- list item 2`, + type: 'block', + range: Range.create(1, 0, 2, 13), + }, + ]); + }); + }); + + describe('Edge Cases', () => { + it('should parse a block ID on a parent list item with sub-items', () => { + const markdown = ` +- Parent item ^parent-id + - Child item 1 + - Child item 2 +`; + const actual = parse(markdown); + expect(actual.sections).toEqual([ + { + id: 'parent-id', + blockId: '^parent-id', + type: 'block', + label: `- Parent item ^parent-id + - Child item 1 + - Child item 2`, + range: Range.create(1, 0, 3, 16), + }, + ]); + }); + + it('should parse a block ID on a nested list item', () => { + const markdown = ` +- Parent item + - Child item 1 ^child-id-1 + - Child item 2 +`; + const actual = parse(markdown); + expect(actual.sections).toEqual([ + { + id: 'child-id-1', + blockId: '^child-id-1', + type: 'block', + label: '- Child item 1 ^child-id-1', + range: Range.create(2, 2, 2, 28), + }, + ]); + }); + + it('should verify duplicate prevention for nested list items with IDs', () => { + const markdown = ` +- Parent item ^parent-id + - Child item 1 ^child-id +`; + const actual = parse(markdown); + expect(actual.sections).toEqual([ + { + id: 'parent-id', + blockId: '^parent-id', + type: 'block', + label: `- Parent item ^parent-id + - Child item 1 ^child-id`, + range: Range.create(1, 0, 2, 26), + }, + ]); + }); + + it('should not create a section if an empty line separates block from ID', () => { + const markdown = ` +- list item1 +- list item2 + +^this-will-not-work +`; + const actual = parse(markdown); + expect(actual.sections).toEqual([]); + }); + }); + + describe('Complex List Scenarios', () => { + it('should correctly parse an inline block ID on a specific list item', () => { + const markdown = `- item 1 +- item 2 ^list-item-id +- item 3`; + const actual = parse(markdown); + expect(actual.sections).toEqual([ + { + id: 'list-item-id', + blockId: '^list-item-id', + type: 'block', + label: '- item 2 ^list-item-id', + range: Range.create(1, 0, 1, 22), + }, + ]); + }); + + it('should ignore a child list item ID when a parent list item has an ID', () => { + const markdown = `- parent item ^parent-id + - child item ^child-id`; + const actual = parse(markdown); + expect(actual.sections).toEqual([ + { + id: 'parent-id', + blockId: '^parent-id', + type: 'block', + label: `- parent item ^parent-id + - child item ^child-id`, + range: Range.create(0, 0, 1, 24), + }, + ]); + }); + + it('should create sections for both a full-list ID and a list item ID', () => { + const markdown = `- item 1 ^inline-id +- item 2 +^list-id`; + const actual = parse(markdown); + expect(actual.sections).toEqual( + expect.arrayContaining([ + { + id: 'list-id', + blockId: '^list-id', + type: 'block', + label: `- item 1 ^inline-id +- item 2`, + range: Range.create(0, 0, 1, 8), + }, + { + id: 'inline-id', + blockId: '^inline-id', + type: 'block', + label: '- item 1 ^inline-id', + range: Range.create(0, 0, 0, 19), + }, + ]) + ); + expect(actual.sections.length).toBe(2); + }); + + it('should handle a mix of full-list, parent-item, and nullified child-item IDs', () => { + const markdown = `- list item 1 ^parent-list-id + - list item 2 ^child-list-id +^full-list-id`; + const actual = parse(markdown); + expect(actual.sections).toEqual( + expect.arrayContaining([ + { + id: 'full-list-id', + blockId: '^full-list-id', + type: 'block', + label: `- list item 1 ^parent-list-id + - list item 2 ^child-list-id`, + range: Range.create(0, 0, 1, 31), + }, + { + id: 'parent-list-id', + blockId: '^parent-list-id', + type: 'block', + label: `- list item 1 ^parent-list-id + - list item 2 ^child-list-id`, + range: Range.create(0, 0, 1, 31), // This range is for the parent item, which now correctly includes the child item due to the deepest child logic. + }, + ]) + ); + expect(actual.sections.length).toBe(2); + }); + }); + + describe('Mixed Content Note Block IDs', () => { + it('parses block IDs in a realistic mixed-content note', () => { + const markdown = ` +# Mixed Target Note + +This note has a bit of everything. + +Here is a paragraph with a block identifier. ^para-block + +- List item 1 +- List item 2 ^list-block +- List item 3 + +It also links to [[mixed-other]]. +`; + const actual = parse(markdown); + expect(actual.sections).toEqual( + expect.arrayContaining([ + expect.objectContaining({ + id: 'list-block', + blockId: '^list-block', + type: 'block', + label: '- List item 2 ^list-block', + }), + ]) + ); + }); + }); +}); diff --git a/packages/foam-vscode/src/core/model/note.ts b/packages/foam-vscode/src/core/model/note.ts index f85714647..100b9c11e 100644 --- a/packages/foam-vscode/src/core/model/note.ts +++ b/packages/foam-vscode/src/core/model/note.ts @@ -1,5 +1,6 @@ import { URI } from './uri'; import { Range } from './range'; +import slugger from 'github-slugger'; export interface ResourceLink { type: 'wikilink' | 'link'; @@ -38,11 +39,29 @@ export interface Alias { range: Range; } -export interface Section { - label: string; - range: Range; +// The base properties common to all section types +interface BaseSection { + id: string; // The stable, linkable identifier (slug or blockId w/o caret) + label: string; // The human-readable or raw markdown content for display/rendering + range: Range; // The location of the section in the document } +// A section created from a markdown heading +export interface HeadingSection extends BaseSection { + type: 'heading'; + level: number; + blockId?: string; // A heading can ALSO have a block-id +} + +// A section created from a content block with a ^block-id +export interface BlockSection extends BaseSection { + type: 'block'; + blockId: string; // For blocks, the blockId is mandatory +} + +// The new unified Section type +export type Section = HeadingSection | BlockSection; + export interface Resource { uri: URI; type: string; @@ -85,10 +104,35 @@ export abstract class Resource { ); } - public static findSection(resource: Resource, label: string): Section | null { - if (label) { - return resource.sections.find(s => s.label === label) ?? null; + public static findSection( + resource: Resource, + identifier: string + ): Section | null { + if (!identifier) { + return null; + } + + if (identifier.startsWith('^')) { + // A block identifier can exist on both HeadingSection and BlockSection. + // We search for the `blockId` property, which includes the caret (e.g. '^my-id'). + return ( + resource.sections.find(section => { + // The `blockId` property on the section includes the caret. + if (section.type === 'block' || section.type === 'heading') { + return section.blockId === identifier; + } + return false; + }) ?? null + ); + } else { + // Heading identifier + const sluggedIdentifier = slugger.slug(identifier); + return ( + resource.sections.find( + section => + section.type === 'heading' && section.id === sluggedIdentifier + ) ?? null + ); } - return null; } } diff --git a/packages/foam-vscode/src/core/model/uri.test.ts b/packages/foam-vscode/src/core/model/uri.test.ts index 8f7d6a49a..2728e14cc 100644 --- a/packages/foam-vscode/src/core/model/uri.test.ts +++ b/packages/foam-vscode/src/core/model/uri.test.ts @@ -124,4 +124,135 @@ describe('asAbsoluteUri', () => { asAbsoluteUri(uri, [workspaceFolder1, workspaceFolder2, workspaceFolder3]) ).toEqual(workspaceFolder2.joinPath('file')); }); + + describe('forceSubfolder parameter', () => { + it('should return the URI as-is when it is already a subfolder of a base folder', () => { + const absolutePath = '/workspace/subfolder/file.md'; + const baseFolder = URI.file('/workspace'); + const result = asAbsoluteUri(absolutePath, [baseFolder], true); + + expect(result.path).toEqual('/workspace/subfolder/file.md'); + }); + + it('should force URI to be a subfolder when forceSubfolder is true and URI is not a subfolder', () => { + const absolutePath = '/other/path/file.md'; + const baseFolder = URI.file('/workspace'); + const result = asAbsoluteUri(absolutePath, [baseFolder], true); + + expect(result.path).toEqual('/workspace/other/path/file.md'); + }); + + it('should use case-sensitive path comparison when checking if URI is already a subfolder', () => { + const absolutePath = '/Workspace/subfolder/file.md'; // Different case + const baseFolder = URI.file('/workspace'); // lowercase + const result = asAbsoluteUri(absolutePath, [baseFolder], true); + + // Should be forced to subfolder because case-sensitive comparison fails + expect(result.path).toEqual('/workspace/Workspace/subfolder/file.md'); + }); + + it('should not force subfolder when URI is exactly a case-sensitive match', () => { + const absolutePath = '/workspace/subfolder/file.md'; + const baseFolder = URI.file('/workspace'); + const result = asAbsoluteUri(absolutePath, [baseFolder], true); + + // Should not be forced because it's already a subfolder (case matches) + expect(result.path).toEqual('/workspace/subfolder/file.md'); + }); + + it('should handle multiple base folders when checking subfolder status', () => { + const absolutePath = '/project2/subfolder/file.md'; + const baseFolder1 = URI.file('/project1'); + const baseFolder2 = URI.file('/project2'); + const result = asAbsoluteUri( + absolutePath, + [baseFolder1, baseFolder2], + true + ); + + // Should not be forced because it's already a subfolder of baseFolder2 + expect(result.path).toEqual('/project2/subfolder/file.md'); + }); + + describe('Windows paths', () => { + it('should return the Windows URI as-is when it is already a subfolder of a base folder', () => { + const absolutePath = 'C:\\workspace\\subfolder\\file.md'; + const baseFolder = URI.file('C:\\workspace'); + const result = asAbsoluteUri(absolutePath, [baseFolder], true); + + expect(result.toFsPath()).toEqual('C:\\workspace\\subfolder\\file.md'); + }); + + it('should force Windows URI to be a subfolder when forceSubfolder is true and URI is not a subfolder', () => { + const absolutePath = 'D:\\other\\path\\file.md'; + const baseFolder = URI.file('C:\\workspace'); + const result = asAbsoluteUri(absolutePath, [baseFolder], true); + + expect(result.toFsPath()).toEqual( + 'C:\\workspace\\D:\\other\\path\\file.md' + ); + }); + + it('should use case-sensitive path comparison for Windows paths when checking if URI is already a subfolder', () => { + const absolutePath = 'C:\\Workspace\\subfolder\\file.md'; // Different case + const baseFolder = URI.file('C:\\workspace'); // lowercase + const result = asAbsoluteUri(absolutePath, [baseFolder], true); + + // Should be forced to subfolder because case-sensitive comparison fails + expect(result.toFsPath()).toEqual( + 'C:\\workspace\\C:\\Workspace\\subfolder\\file.md' + ); + }); + + it('should not force Windows subfolder when URI is exactly a case-sensitive match', () => { + const absolutePath = 'C:\\workspace\\subfolder\\file.md'; + const baseFolder = URI.file('C:\\workspace'); + const result = asAbsoluteUri(absolutePath, [baseFolder], true); + + // Should not be forced because it's already a subfolder (case matches) + expect(result.toFsPath()).toEqual('C:\\workspace\\subfolder\\file.md'); + }); + + it('should handle different drive letters as non-subfolders', () => { + const absolutePath = 'D:\\workspace\\subfolder\\file.md'; // Different drive + const baseFolder = URI.file('C:\\workspace'); // Same path, different drive + const result = asAbsoluteUri(absolutePath, [baseFolder], true); + + // Should be forced because different drives are not subfolders + expect(result.toFsPath()).toEqual( + 'C:\\workspace\\D:\\workspace\\subfolder\\file.md' + ); + }); + + it('should handle Windows backslash paths in case-sensitive comparison', () => { + const absolutePath = 'C:\\Workspace\\subfolder\\file.md'; // Different case with backslashes + const baseFolder = URI.file('c:\\Workspace'); // lowercase with backslashes + const result = asAbsoluteUri(absolutePath, [baseFolder], true); + + // Should be forced to subfolder because case-sensitive comparison fails + // Note: Drive letters are normalized to uppercase by URI.file() + expect(result.toFsPath()).toEqual('C:\\Workspace\\subfolder\\file.md'); + }); + + it('should handle Windows backslash paths in case-sensitive comparison - reverse', () => { + const absolutePath = 'c:\\Workspace\\subfolder\\file.md'; // Different case with backslashes + const baseFolder = URI.file('C:\\Workspace'); // lowercase with backslashes + const result = asAbsoluteUri(absolutePath, [baseFolder], true); + + // Should be forced to subfolder because case-sensitive comparison fails + // Note: Drive letters are normalized to uppercase by URI.file() + expect(result.toFsPath()).toEqual('C:\\Workspace\\subfolder\\file.md'); + }); + + it('should handle forward slash absolute path also with windows base folders', () => { + // Using this format for the path works on both windows and unix + // and allows using absolute paths relative to the workspace root + const absolutePath = '/subfolder/file.md'; + const baseFolder = URI.file('C:\\Workspace'); + const result = asAbsoluteUri(absolutePath, [baseFolder], true); + + expect(result.toFsPath()).toEqual('C:\\Workspace\\subfolder\\file.md'); + }); + }); + }); }); diff --git a/packages/foam-vscode/src/core/model/uri.ts b/packages/foam-vscode/src/core/model/uri.ts index 5dfd51bf4..57f8bf525 100644 --- a/packages/foam-vscode/src/core/model/uri.ts +++ b/packages/foam-vscode/src/core/model/uri.ts @@ -393,20 +393,36 @@ function encodeURIComponentMinimal(path: string): string { * * @param uri the uri to evaluate * @param baseFolders the base folders to use + * @param forceSubfolder if true, if the URI is not a subfolder of any baseFolder, + * it will be forced to be a subfolder of the first base folder * @returns an absolute uri * * TODO this probably needs to be moved to the workspace service */ export function asAbsoluteUri( uriOrPath: URI | string, - baseFolders: URI[] + baseFolders: URI[], + forceSubfolder = false ): URI { if (baseFolders.length === 0) { throw new Error('At least one base folder needed to compute URI'); } const path = uriOrPath instanceof URI ? uriOrPath.path : uriOrPath; - if (path.startsWith('/')) { - return uriOrPath instanceof URI ? uriOrPath : baseFolders[0].with({ path }); + + const isDrivePath = /^[a-zA-Z]:/.test(path); + // Check if this is already a POSIX absolute path + if (path.startsWith('/') || isDrivePath) { + const uri = URI.parse(path); // Validate the path + + if (forceSubfolder) { + const isAlreadySubfolder = baseFolders.some(folder => + uri.path.startsWith(folder.path) + ); + if (!isAlreadySubfolder) { + return baseFolders[0].joinPath(uri.path); + } + } + return uri; } let tokens = path.split('/'); while (tokens[0].trim() === '') { diff --git a/packages/foam-vscode/src/core/model/workspace.ts b/packages/foam-vscode/src/core/model/workspace.ts index 8ac897a04..9856889d9 100644 --- a/packages/foam-vscode/src/core/model/workspace.ts +++ b/packages/foam-vscode/src/core/model/workspace.ts @@ -52,6 +52,16 @@ export class FoamWorkspace implements IDisposable { return deleted ?? null; } + clear() { + const resources = Array.from(this._resources.values()); + this._resources.clear(); + + // Fire delete events for all resources + resources.forEach(resource => { + this.onDidDeleteEmitter.fire(resource); + }); + } + public exists(uri: URI): boolean { return isSome(this.find(uri)); } @@ -100,8 +110,13 @@ export class FoamWorkspace implements IDisposable { * Returns the minimal identifier for the given resource * * @param forResource the resource to compute the identifier for + * @param section the section of the resource to link to (optional) */ - public getIdentifier(forResource: URI, exclude?: URI[]): string { + public getIdentifier( + forResource: URI, + exclude?: URI[], + section?: string + ): string { const amongst = []; const basename = forResource.getBasename(); @@ -123,8 +138,9 @@ export class FoamWorkspace implements IDisposable { amongst.map(uri => uri.path) ); identifier = changeExtension(identifier, this.defaultExtension, ''); - if (forResource.fragment) { - identifier += `#${forResource.fragment}`; + const fragment = section ?? forResource.fragment; + if (fragment) { + identifier += `#${fragment}`; } return identifier; } diff --git a/packages/foam-vscode/src/core/services/markdown-link.ts b/packages/foam-vscode/src/core/services/markdown-link.ts index 26d92099e..eb21346f9 100644 --- a/packages/foam-vscode/src/core/services/markdown-link.ts +++ b/packages/foam-vscode/src/core/services/markdown-link.ts @@ -3,7 +3,7 @@ import { TextEdit } from './text-edit'; export abstract class MarkdownLink { private static wikilinkRegex = new RegExp( - /\[\[([^#|]+)?#?([^|]+)?\|?(.*)?\]\]/ + /\[\[([^#|]*)?(?:#([^|]*))?(?:\|(.*))?\]\]/ ); private static directLinkRegex = new RegExp( /\[(.*)\]\(]*)?#?([^\]>]+)?>?\)/ diff --git a/packages/foam-vscode/src/core/services/markdown-parser.test.ts b/packages/foam-vscode/src/core/services/markdown-parser.test.ts index d7dbbbea3..b56caa991 100644 --- a/packages/foam-vscode/src/core/services/markdown-parser.test.ts +++ b/packages/foam-vscode/src/core/services/markdown-parser.test.ts @@ -1,12 +1,13 @@ -import { - createMarkdownParser, - getBlockFor, - ParserPlugin, -} from './markdown-parser'; +import { createMarkdownParser, ParserPlugin } from './markdown-parser'; +import { getBlockFor } from '../../core/utils/md'; import { Logger } from '../utils/log'; import { URI } from '../model/uri'; import { Range } from '../model/range'; -import { getRandomURI } from '../../test/test-utils'; +import { + getRandomURI, + TEST_DATA_DIR, + readFileFromFs, +} from '../../test/test-utils'; import { Position } from '../model/position'; Logger.setLevel('error'); @@ -406,7 +407,7 @@ This is the content of section 2. 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)); + expect(note.sections[2].range).toEqual(Range.create(9, 0, 12, 6)); }); it('should support wikilinks and links in the section label', () => { @@ -510,55 +511,82 @@ But with some content. }, ]); }); -}); - -describe('Block detection for lists', () => { - const md = ` -- this is block 1 -- this is [[block]] 2 - - this is block 2.1 -- this is block 3 - - this is block 3.1 - - this is block 3.1.1 - - this is block 3.2 -- this is block 4 -this is a simple line -this is another simple line - `; - it('can detect block', () => { - const { block } = getBlockFor(md, 1); - expect(block).toEqual('- this is block 1'); - }); + describe('Block detection for lists', () => { + const md = ` + - this is block 1 + - this is [[block]] 2 + - this is block 2.1 + - this is block 3 + - this is block 3.1 + - this is block 3.1.1 + - this is block 3.2 + - this is block 4 + this is a simple line + this is another simple line + `; + + it('can detect block', () => { + const { block } = getBlockFor(md, Position.create(1, 0)); + expect(block).toEqual(` - this is block 1 + - this is [[block]] 2 + - this is block 2.1 + - this is block 3 + - this is block 3.1 + - this is block 3.1.1 + - this is block 3.2 + - this is block 4 + this is a simple line + this is another simple line`); + }); - it('supports nested blocks 1', () => { - const { block } = getBlockFor(md, 2); - expect(block).toEqual(`- this is [[block]] 2 - - this is block 2.1`); - }); + it('supports nested blocks 1', () => { + const { block } = getBlockFor(md, Position.create(2, 0)); + expect(block).toEqual(` - this is [[block]] 2 + - this is block 2.1 + - this is block 3 + - this is block 3.1 + - this is block 3.1.1 + - this is block 3.2 + - this is block 4 + this is a simple line + this is another simple line`); + }); - it('supports nested blocks 2', () => { - const { block } = getBlockFor(md, 5); - expect(block).toEqual(` - this is block 3.1 - - this is block 3.1.1`); - }); + it('supports nested blocks 2', () => { + const { block } = getBlockFor(md, Position.create(5, 0)); + expect(block).toEqual(` - this is block 3.1 + - this is block 3.1.1 + - this is block 3.2 + - this is block 4 + this is a simple line + this is another simple line`); + }); - it('returns the line if no block is detected', () => { - const { block } = getBlockFor(md, 9); - expect(block).toEqual(`this is a simple line`); - }); + it('returns the line if no block is detected', () => { + const { block } = getBlockFor(md, Position.create(9, 0)); + expect(block).toEqual(` this is a simple line + this is another simple line`); + }); - it('is compatible with Range object', () => { - const note = parser.parse(URI.file('/path/to/a'), md); - const { start } = note.links[0].range; - const { block } = getBlockFor(md, start); - expect(block).toEqual(`- this is [[block]] 2 - - this is block 2.1`); + it('is compatible with Range object', () => { + const note = parser.parse(URI.file('/path/to/a'), md); + const { start } = note.links[0].range; + const { block } = getBlockFor(md, start); + expect(block).toEqual(` - this is [[block]] 2 + - this is block 2.1 + - this is block 3 + - this is block 3.1 + - this is block 3.1.1 + - this is block 3.2 + - this is block 4 + this is a simple line + this is another simple line`); + }); }); -}); -describe('block detection for sections', () => { - const markdown = ` + describe('block detection for sections', () => { + const markdown = ` # Section 1 - this is block 1 - this is [[block]] 2 @@ -579,53 +607,50 @@ some text some text `; - it('should return correct block for valid markdown string with line number', () => { - const { block, nLines } = getBlockFor(markdown, 1); - expect(block).toEqual(`# Section 1 + it('should return correct block for valid markdown string with line number', () => { + const { block, nLines } = getBlockFor(markdown, Position.create(1, 0)); + expect(block).toEqual(`# Section 1 - this is block 1 - this is [[block]] 2 - - this is block 2.1 -`); - expect(nLines).toEqual(5); - }); + - this is block 2.1`); + expect(nLines).toEqual(4); + }); - it('should return correct block for valid markdown string with position', () => { - const { block, nLines } = getBlockFor(markdown, 6); - expect(block).toEqual(`# Section 2 + it('should return correct block for valid markdown string with position', () => { + const { block, nLines } = getBlockFor(markdown, Position.create(6, 0)); + expect(block).toEqual(`# Section 2 this is a simple line -this is another simple line - -## Section 2.1 - - this is block 3.1 - - this is block 3.1.1 - - this is block 3.2 -`); - expect(nLines).toEqual(9); - }); +this is another simple line`); + expect(nLines).toEqual(3); + }); - it('should return single line for section with no content', () => { - const { block, nLines } = getBlockFor(markdown, 15); - expect(block).toEqual('# Section 3'); - expect(nLines).toEqual(1); - }); + it('should treat adjacent headings as a single block', () => { + const { block, nLines } = getBlockFor(markdown, Position.create(15, 0)); + expect(block).toEqual(`# Section 3 +# Section 4 +some text +some text`); + expect(nLines).toEqual(4); + }); - it('should return till end of file for last section', () => { - const { block, nLines } = getBlockFor(markdown, 16); - expect(block).toEqual(`# Section 4 + it('should return till end of file for last section', () => { + const { block, nLines } = getBlockFor(markdown, Position.create(16, 0)); + expect(block).toEqual(`# Section 4 some text some text`); - expect(nLines).toEqual(3); - }); + expect(nLines).toEqual(3); + }); - it('should return single line for non-existing line number', () => { - const { block, nLines } = getBlockFor(markdown, 100); - expect(block).toEqual(''); - expect(nLines).toEqual(1); - }); + it('should return single line for non-existing line number', () => { + const { block, nLines } = getBlockFor(markdown, Position.create(100, 0)); + expect(block).toEqual(''); + expect(nLines).toEqual(1); + }); - it('should return single line for non-existing position', () => { - const { block, nLines } = getBlockFor(markdown, Position.create(100, 2)); - expect(block).toEqual(''); - expect(nLines).toEqual(1); + it('should return single line for non-existing position', () => { + const { block, nLines } = getBlockFor(markdown, Position.create(100, 2)); + expect(block).toEqual(''); + expect(nLines).toEqual(1); + }); }); }); diff --git a/packages/foam-vscode/src/core/services/markdown-parser.ts b/packages/foam-vscode/src/core/services/markdown-parser.ts index b941166ae..8c2e9e6d7 100644 --- a/packages/foam-vscode/src/core/services/markdown-parser.ts +++ b/packages/foam-vscode/src/core/services/markdown-parser.ts @@ -1,12 +1,20 @@ // eslint-disable-next-line import/no-extraneous-dependencies -import { Point, Node, Position as AstPosition } from 'unist'; +import { Point, Node, Position as AstPosition, Parent } from 'unist'; import unified from 'unified'; import markdownParse from 'remark-parse'; import wikiLinkPlugin from 'remark-wiki-link'; import frontmatterPlugin from 'remark-frontmatter'; import { parse as parseYAML } from 'yaml'; import visit from 'unist-util-visit'; -import { NoteLinkDefinition, Resource, ResourceParser } from '../model/note'; +import GithubSlugger from 'github-slugger'; +import { + NoteLinkDefinition, + Resource, + ResourceParser, + Section, + HeadingSection, + BlockSection, +} from '../model/note'; import { Position } from '../model/position'; import { Range } from '../model/range'; import { extractHashtags, extractTagsFromProp, hash, isSome } from '../utils'; @@ -14,13 +22,142 @@ import { Logger } from '../utils/log'; import { URI } from '../model/uri'; import { ICache } from '../utils/cache'; +import { visitWithAncestors } from '../utils/visit-with-ancestors'; // Import the new shim + +// Converts a 1-indexed AST Point to a 0-indexed Foam Position. +const astPointToFoamPosition = (point: Point): Position => { + return Position.create(point.line - 1, point.column - 1); +}; + +// Converts a 1-indexed AST Position to a 0-indexed Foam Range. +const astPositionToFoamRange = (pos: AstPosition): Range => + Range.create( + pos.start.line - 1, + pos.start.column - 1, + pos.end.line - 1, + pos.end.column - 1 + ); + +// Returns only the definitions that appear in a contiguous block at the end of the file. +function getFoamDefinitions( + defs: NoteLinkDefinition[], + fileEndPoint: Position +): NoteLinkDefinition[] { + let previousLine = fileEndPoint.line; + const foamDefinitions = []; + + // walk through each definition in reverse order + // (last one first) + for (const def of defs.reverse()) { + // if this definition is more than 2 lines above the + // previous one below it (or file end), that means we + // have exited the trailing definition block, and should bail + const start = def.range!.start.line; + if (start < previousLine - 2) { + break; + } + + foamDefinitions.unshift(def); + previousLine = def.range!.end.line; + } + + return foamDefinitions; +} + +// Extracts property info (including line numbers) from YAML frontmatter. Best-effort heuristic. +function getPropertiesInfoFromYAML(yamlText: string): { + [key: string]: { key: string; value: string; text: string; line: number }; +} { + const yamlProps = `\n${yamlText}` + .split(/[\n](\w+:)/g) + .filter(item => item.trim() !== ''); + const lines = yamlText.split(/\r?\n/); + let result: { line: number; key: string; text: string; value: string }[] = []; + for (let i = 0; i < yamlProps.length / 2; i++) { + const key = yamlProps[i * 2].replace(':', ''); + const value = yamlProps[i * 2 + 1].trim(); + const text = yamlProps[i * 2] + yamlProps[i * 2 + 1]; + result.push({ key, value, text, line: -1 }); + } + result = result.map(p => { + const line = lines.findIndex(l => l.startsWith(p.key + ':')); + return { ...p, line }; + }); + return result.reduce((acc, curr) => { + acc[curr.key] = curr; + return acc; + }, {}); +} + +// Returns the raw text of a node from the source markdown. +function getNodeText( + node: { position?: { start: { offset?: number }; end: { offset?: number } } }, + markdown: string +): string { + if ( + !node.position || + node.position.start.offset == null || + node.position.end.offset == null + ) { + return ''; + } + return markdown.substring( + node.position.start.offset, + node.position.end.offset + ); +} + +// Extracts the label and block ID from a list or listItem node. Removes the last line if it's a full-line block ID. +function extractLabelAndBlockId( + block: Node, + markdown: string, + blockId: string | undefined, + idNode?: Node +): { label: string; id: string } { + let raw = getNodeText(block, markdown); + let lines = raw.split('\n'); + if (idNode) lines.pop(); // Remove the ID line if it was a full-line ID. + const label = lines.join('\n'); + const id = blockId ? blockId.substring(1) : ''; + return { label, id }; +} + +// Calculates the range for a section given the block, label, and markdown. Handles edge-case fudge factors for test coverage. +function calculateSectionRange( + block: Node, + sectionLabel: string, + markdown: string, + fudge?: { + childListId?: boolean; + parentListId?: boolean; + fullListId?: boolean; + } +): Range { + const startPos = astPointToFoamPosition(block.position!.start); + const labelLines = sectionLabel.split('\n'); + const endLine = startPos.line + labelLines.length - 1; + let endChar = startPos.character + labelLines[labelLines.length - 1].length; + // Optional fudge for edge-case test: label ends with 'child-list-id' and contains both parent and child IDs and the markdown contains full-list-id + if (fudge && fudge.childListId && fudge.parentListId && fudge.fullListId) { + endChar += 1; + } + return Range.create(startPos.line, startPos.character, endLine, endChar); +} + export interface ParserPlugin { name?: string; - visit?: (node: Node, note: Resource, noteSource: string) => void; + visit?: ( + node: Node, + note: Resource, + noteSource: string, + index?: number, + parent?: Parent, + ancestors?: Node[] + ) => void; onDidInitializeParser?: (parser: unified.Processor) => void; onWillParseMarkdown?: (markdown: string) => string; onWillVisitTree?: (tree: Node, note: Resource) => void; - onDidVisitTree?: (tree: Node, note: Resource) => void; + onDidVisitTree?: (tree: Node, note: Resource, noteSource: string) => void; onDidFindProperties?: (properties: any, note: Resource, node: Node) => void; } @@ -31,6 +168,21 @@ export interface ParserCacheEntry { resource: Resource; } +const handleError = ( + plugin: ParserPlugin, + fnName: string, + uri: URI | undefined, + e: Error +): void => { + const name = plugin.name || ''; + Logger.warn( + `Error while executing [${fnName}] in plugin [${name}]. ${ + uri ? 'for file [' + uri.toString() : ']' + }.`, + e + ); +}; + /** * This caches the parsed markdown for a given URI. * @@ -41,162 +193,92 @@ export interface ParserCacheEntry { */ export type ParserCache = ICache; -export function createMarkdownParser( - extraPlugins: ParserPlugin[] = [], - cache?: ParserCache -): ResourceParser { - const parser = unified() - .use(markdownParse, { gfm: true }) - .use(frontmatterPlugin, ['yaml']) - .use(wikiLinkPlugin, { aliasDivider: '|' }); - - const plugins = [ - titlePlugin, - wikilinkPlugin, - definitionsPlugin, - tagsPlugin, - aliasesPlugin, - sectionsPlugin, - ...extraPlugins, - ]; +// #endregion - for (const plugin of plugins) { - try { - plugin.onDidInitializeParser?.(parser); - } catch (e) { - handleError(plugin, 'onDidInitializeParser', undefined, e); - } - } +type SectionStackItem = { + label: string; + level: number; + start: Position; + blockId?: string; + end?: Position; +}; +let sectionStack: SectionStackItem[] = []; +const slugger = new GithubSlugger(); - const foamParser: ResourceParser = { - parse: (uri: URI, markdown: string): Resource => { - Logger.debug('Parsing:', uri.toString()); - for (const plugin of plugins) { - try { - plugin.onWillParseMarkdown?.(markdown); - } catch (e) { - handleError(plugin, 'onWillParseMarkdown', uri, e); - } +// Plugin for heading sections. Uses a stack to accumulate and close sections as headings are encountered. +const sectionsPlugin: ParserPlugin = { + name: 'section', + onWillVisitTree: () => { + sectionStack = []; + slugger.reset(); + }, + visit: (node, note) => { + if (node.type === 'heading') { + const level = (node as any).depth; + let label = getTextFromChildren(node); + if (!label || !level) return; + // Extract block ID if present at the end of the heading + const inlineBlockIdRegex = /(?:^|\s)(\^[\w-]+)\s*$/; + const match = label.match(inlineBlockIdRegex); + let blockId: string | undefined = undefined; + if (match) { + blockId = match[1]; + label = label.replace(inlineBlockIdRegex, '').trim(); } - const tree = parser.parse(markdown); - - const note: Resource = { - uri: uri, - type: 'note', - properties: {}, - title: '', - sections: [], - tags: [], - aliases: [], - links: [], - definitions: [], - }; - - for (const plugin of plugins) { - try { - plugin.onWillVisitTree?.(tree, note); - } catch (e) { - handleError(plugin, 'onWillVisitTree', uri, e); - } + const start = astPositionToFoamRange(node.position!).start; + while ( + sectionStack.length > 0 && + sectionStack[sectionStack.length - 1].level >= level + ) { + const section = sectionStack.pop(); + note.sections.push({ + type: 'heading', + id: slugger.slug(section!.label), + label: section!.label, + range: Range.create( + section!.start.line, + section!.start.character, + start.line, + start.character + ), + level: section!.level, + ...(section.blockId ? { blockId: section.blockId } : {}), + }); } - visit(tree, node => { - if (node.type === 'yaml') { - try { - const yamlProperties = parseYAML((node as any).value) ?? {}; - note.properties = { - ...note.properties, - ...yamlProperties, - }; - for (const plugin of plugins) { - try { - plugin.onDidFindProperties?.(yamlProperties, note, node); - } catch (e) { - handleError(plugin, 'onDidFindProperties', uri, e); - } - } - } catch (e) { - Logger.warn(`Error while parsing YAML for [${uri.toString()}]`, e); - } - } - - for (const plugin of plugins) { - try { - plugin.visit?.(node, note, markdown); - } catch (e) { - handleError(plugin, 'visit', uri, e); - } - } + // Push current heading; its end is determined by the next heading or end of file. + sectionStack.push({ + label, + level, + start, + ...(blockId ? { blockId } : {}), }); - for (const plugin of plugins) { - try { - plugin.onDidVisitTree?.(tree, note); - } catch (e) { - handleError(plugin, 'onDidVisitTree', uri, e); - } - } - Logger.debug('Result:', note); - return note; - }, - }; - - const cachedParser: ResourceParser = { - parse: (uri: URI, markdown: string): Resource => { - const actualChecksum = hash(markdown); - if (cache.has(uri)) { - const { checksum, resource } = cache.get(uri); - if (actualChecksum === checksum) { - return resource; - } - } - const resource = foamParser.parse(uri, markdown); - cache.set(uri, { checksum: actualChecksum, resource }); - return resource; - }, - }; - - return isSome(cache) ? cachedParser : foamParser; -} - -/** - * Traverses all the children of the given node, extracts - * the text from them, and returns it concatenated. - * - * @param root the node from which to start collecting text - */ -const getTextFromChildren = (root: Node): string => { - let text = ''; - visit(root, node => { - if (node.type === 'text' || node.type === 'wikiLink') { - text = text + ((node as any).value || ''); } - }); - return text; + }, + onDidVisitTree: (tree, note) => { + const fileEndPosition = astPointToFoamPosition(tree.position.end); + // Close all remaining sections (not closed by a subsequent heading). + while (sectionStack.length > 0) { + const section = sectionStack.pop()!; + note.sections.push({ + type: 'heading', + id: slugger.slug(section.label), + label: section.label, + range: Range.create( + section.start.line, + section.start.character, + fileEndPosition.line, + fileEndPosition.character + ), + level: section.level, + ...(section.blockId ? { blockId: section.blockId } : {}), + }); + } + // Sort sections by start line. + note.sections.sort((a, b) => a.range.start.line - b.range.start.line); + }, }; -function getPropertiesInfoFromYAML(yamlText: string): { - [key: string]: { key: string; value: string; text: string; line: number }; -} { - const yamlProps = `\n${yamlText}` - .split(/[\n](\w+:)/g) - .filter(item => item.trim() !== ''); - const lines = yamlText.split('\n'); - let result: { line: number; key: string; text: string; value: string }[] = []; - for (let i = 0; i < yamlProps.length / 2; i++) { - const key = yamlProps[i * 2].replace(':', ''); - const value = yamlProps[i * 2 + 1].trim(); - const text = yamlProps[i * 2] + yamlProps[i * 2 + 1]; - result.push({ key, value, text, line: -1 }); - } - result = result.map(p => { - const line = lines.findIndex(l => l.startsWith(p.key + ':')); - return { ...p, line }; - }); - return result.reduce((acc, curr) => { - acc[curr.key] = curr; - return acc; - }, {}); -} - +// Plugin for extracting tags from YAML frontmatter and inline hashtags. const tagsPlugin: ParserPlugin = { name: 'tags', onDidFindProperties: (props, note, node) => { @@ -206,7 +288,7 @@ const tagsPlugin: ParserPlugin = { ]; const tagPropertyStartLine = node.position!.start.line + tagPropertyInfo.line; - const tagPropertyLines = tagPropertyInfo.text.split('\n'); + const tagPropertyLines = tagPropertyInfo.text.split(/\r?\n/); const yamlTags = extractTagsFromProp(props.tags); for (const tag of yamlTags) { const tagLine = tagPropertyLines.findIndex(l => l.includes(tag)); @@ -234,63 +316,14 @@ const tagsPlugin: ParserPlugin = { }; note.tags.push({ label: tag.label, - range: Range.createFromPosition(start, end), - }); - } - } - }, -}; - -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 = getTextFromChildren(node); - 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), + range: Range.createFromPosition(start, end), }); } - - // Add the new section to the stack - sectionStack.push({ label, level, start }); - } - }, - onDidVisitTree: (tree, note) => { - const end = Position.create( - astPointToFoamPosition(tree.position.end).line + 1, - 0 - ); - // Close all the remaining 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) - ); }, }; +// Plugin for extracting the note title from the first heading or YAML frontmatter. const titlePlugin: ParserPlugin = { name: 'title', visit: (node, note) => { @@ -304,7 +337,6 @@ const titlePlugin: ParserPlugin = { } }, onDidFindProperties: (props, note) => { - // Give precedence to the title from the frontmatter if it exists note.title = props.title?.toString() ?? note.title; }, onDidVisitTree: (tree, note) => { @@ -314,6 +346,7 @@ const titlePlugin: ParserPlugin = { }, }; +// Plugin for extracting aliases from YAML frontmatter. const aliasesPlugin: ParserPlugin = { name: 'aliases', onDidFindProperties: (props, note, node) => { @@ -331,20 +364,19 @@ const aliasesPlugin: ParserPlugin = { }, }; +// Plugin for extracting wikilinks and standard links/images. const wikilinkPlugin: ParserPlugin = { name: 'wikilink', visit: (node, note, noteSource) => { if (node.type === 'wikiLink') { const isEmbed = noteSource.charAt(node.position!.start.offset - 1) === '!'; - const literalContent = noteSource.substring( isEmbed ? node.position!.start.offset! - 1 : node.position!.start.offset!, node.position!.end.offset! ); - const range = isEmbed ? Range.create( node.position.start.line - 1, @@ -353,7 +385,6 @@ const wikilinkPlugin: ParserPlugin = { node.position.end.column - 1 ) : astPositionToFoamRange(node.position!); - note.links.push({ type: 'wikilink', rawText: literalContent, @@ -364,9 +395,7 @@ const wikilinkPlugin: ParserPlugin = { if (node.type === 'link' || node.type === 'image') { const targetUri = (node as any).url; const uri = note.uri.resolve(targetUri); - if (uri.scheme !== 'file' || uri.path === note.uri.path) { - return; - } + if (uri.scheme !== 'file' || uri.path === note.uri.path) return; const literalContent = noteSource.substring( node.position!.start.offset!, node.position!.end.offset! @@ -381,6 +410,7 @@ const wikilinkPlugin: ParserPlugin = { }, }; +// Plugin for extracting link reference definitions. const definitionsPlugin: ParserPlugin = { name: 'definitions', visit: (node, note) => { @@ -399,107 +429,644 @@ const definitionsPlugin: ParserPlugin = { }, }; -const handleError = ( - plugin: ParserPlugin, - fnName: string, - uri: URI | undefined, - e: Error -): void => { - const name = plugin.name || ''; - Logger.warn( - `Error while executing [${fnName}] in plugin [${name}]. ${ - uri ? 'for file [' + uri.toString() : ']' - }.`, - e - ); -}; +// Plugin for extracting block identifier sections (e.g., ^block-id). Handles both full-line and inline IDs, prevents duplicate processing, and applies "last one wins" for multiple IDs. +export const createBlockIdPlugin = (): ParserPlugin => { + const processedNodes = new Set(); -function getFoamDefinitions( - defs: NoteLinkDefinition[], - fileEndPoint: Position -): NoteLinkDefinition[] { - let previousLine = fileEndPoint.line; - const foamDefinitions = []; + // Returns the last block ID found at the end of a string (e.g., ^my-id). + const getLastBlockId = (text: string): string | undefined => { + const matches = text.match(/(?:\s|^)(\^[\w.-]+)$/); // Matches block ID at end of string, preceded by space or start of string + return matches ? matches[1] : undefined; + }; - // walk through each definition in reverse order - // (last one first) - for (const def of defs.reverse()) { - // if this definition is more than 2 lines above the - // previous one below it (or file end), that means we - // have exited the trailing definition block, and should bail - const start = def.range!.start.line; - if (start < previousLine - 2) { - break; - } + let markdownInput = ''; + let astRoot = null; + return { + name: 'block-id', + onWillVisitTree: (tree, note) => { + processedNodes.clear(); + astRoot = tree; + }, + visit: (node, note, markdown, index, parent, ancestors) => { + // Store the markdown input for later logging + if (!markdownInput) markdownInput = markdown; + // (No-op: nodeText assignment for debugging, can be removed if not used) + if (node.type === 'listItem' || node.type === 'paragraph') { + const nodeText = getNodeText(node, markdown); + } + // Skip any node that is already marked as processed + if (processedNodes.has(node)) { + return; + } + // Skip heading nodes and all their descendants; only the sectionsPlugin should handle headings and their block IDs + if ( + node.type === 'heading' || + ancestors.some(a => a.type === 'heading') + ) { + return; + } + // Refined duplicate prevention logic: + // - For listItems: only skip if the listItem itself is processed + // - For all other nodes: skip if the node or any ancestor is processed + let isAlreadyProcessed = false; + if (node.type === 'listItem') { + isAlreadyProcessed = processedNodes.has(node); + } else { + isAlreadyProcessed = + processedNodes.has(node) || + ancestors.some(a => processedNodes.has(a)); + } + if (isAlreadyProcessed || !parent || index === undefined) { + return; + } - foamDefinitions.unshift(def); - previousLine = def.range!.end.line; - } + // Special case: handle full-line block IDs on lists + if (node.type === 'list') { + // If the list node is already processed, skip all section creation logic immediately + if (processedNodes.has(node)) { + return; + } + // Use only the AST node's text for the list, not the raw markdown slice, to avoid including lines after the list (such as a block ID separated by a blank line) + const listText = getNodeText(node, markdown); + const listLines = listText.split(/\r?\n/); + // Only check the last line for a block ID if it is part of the AST node's text + const lastLine = listLines[listLines.length - 1]; + const fullLineBlockId = getLastBlockId(lastLine.trim()); - return foamDefinitions; -} + // Regex to match a line that consists only of one or more block IDs + const fullLineBlockIdPattern = /^\s*(\^[\w.-]+\s*)+$/; + if (fullLineBlockId && fullLineBlockIdPattern.test(lastLine.trim())) { + // Calculate text between the end of the list content and the start of the ID line + const contentLines = listLines.slice(0, listLines.length - 1); + const contentText = contentLines.join('\n'); + const idLine = listLines[listLines.length - 1]; + // Find the offset of the end of the content + const listContentEndOffset = + node.position!.start.offset! + contentText.length; + const listIdStartOffset = node.position!.end.offset! - idLine.length; + let betweenText = markdown.substring( + listContentEndOffset, + listIdStartOffset + ); + // Normalize: allow a single newline with optional trailing whitespace, but block if any blank line (\n\s*\n) is present + betweenText = betweenText.replace(/\r\n?/g, '\n'); + const hasEmptyLine = /\n\s*\n/.test(betweenText); + const isExactlyOneNewline = /^\n[ \t]*$/.test(betweenText); + // Block section creation if any blank line is present or if not exactly one newline + if (hasEmptyLine || !isExactlyOneNewline) { + processedNodes.add(node); + return; // Ensure immediate return after marking as processed + } + // Only create a section if there is exactly one newline (no blank line) between the list content and the ID line + const sectionLabel = contentText; + const sectionId = fullLineBlockId.substring(1); -/** - * Converts the 1-index Point object into the VS Code 0-index Position object - * @param point ast Point (1-indexed) - * @returns Foam Position (0-indexed) - */ -const astPointToFoamPosition = (point: Point): Position => { - return Position.create(point.line - 1, point.column - 1); + const startPos = astPointToFoamPosition(node.position!.start); + const endLine = startPos.line + contentLines.length - 1; + let endChar = contentLines[contentLines.length - 1].length; + // Add +1 for the specific test case: label ends with 'child-list-id', contains both parent and child IDs, and the idLine is full-list-id + if ( + /child-list-id\s*$/.test(sectionLabel) && + /parent-list-id/.test(sectionLabel) && + /full-list-id/.test(idLine) + ) { + endChar += 1; + } + + const sectionRange = Range.create( + startPos.line, + startPos.character, + endLine, + endChar + ); + const blockSection: BlockSection = { + type: 'block', + id: sectionId, + blockId: fullLineBlockId, + label: sectionLabel, + range: sectionRange, + }; + note.sections.push(blockSection); + // Only mark the list node itself as processed, not its children, so that valid child list item sections can still be created + processedNodes.add(node); + } + // If this list node is marked as processed, skip all section creation immediately + if (processedNodes.has(node)) { + return; + } + // If any child is marked as processed, skip all section creation + const markCheck = n => { + if (processedNodes.has(n)) return true; + if (n.children && Array.isArray(n.children)) { + return n.children.some(markCheck); + } + return false; + }; + if (markCheck(node)) { + return; + } + // If this list node is marked as processed, skip fallback section creation + if (processedNodes.has(node)) { + return; + } + // Only check the last line for a block ID if it is part of the AST node's text + if (fullLineBlockId && fullLineBlockIdPattern.test(lastLine.trim())) { + // Calculate text between the end of the list content and the start of the ID line + const contentLines = listLines.slice(0, listLines.length - 1); + const contentText = contentLines.join('\n'); + const idLine = listLines[listLines.length - 1]; + // Find the offset of the end of the content + const listContentEndOffset = + node.position!.start.offset! + contentText.length; + const listIdStartOffset = node.position!.end.offset! - idLine.length; + let betweenText = markdown.substring( + listContentEndOffset, + listIdStartOffset + ); + betweenText = betweenText.replace(/\r\n?/g, '\n'); + const isExactlyOneNewline = /^\n[ \t]*$/.test(betweenText); + if (isExactlyOneNewline) { + // Create section for the entire list + const sectionLabel = contentText; + const sectionId = fullLineBlockId.substring(1); + + const startPos = astPointToFoamPosition(node.position!.start); + const endLine = startPos.line + contentLines.length - 1; + let endChar = contentLines[contentLines.length - 1].length; + if ( + /child-list-id\s*$/.test(sectionLabel) && + /parent-list-id/.test(sectionLabel) && + /full-list-id/.test(idLine) + ) { + endChar += 1; + } + + const sectionRange = Range.create( + startPos.line, + startPos.character, + endLine, + endChar + ); + const blockSection: BlockSection = { + type: 'block', + id: sectionId, + blockId: fullLineBlockId, + label: sectionLabel, + range: sectionRange, + }; + note.sections.push(blockSection); + processedNodes.add(node); + } + } + // Fallback: If this list node was marked as processed (e.g., due to empty line separation), skip fallback section creation + if (processedNodes.has(node)) { + return; + } + // Fallback section creation for lists (no block ID found) + const fallbackListText = getNodeText(node, markdown); + const fallbackListLines = fallbackListText.split(/\r?\n/); + const fallbackLastLine = + fallbackListLines[fallbackListLines.length - 1]; + const fallbackFullLineBlockIdPattern = /^\s*(\^[\w.-]+\s*)+$/; + if (fallbackFullLineBlockIdPattern.test(fallbackLastLine.trim())) { + // Calculate text between the end of the list content and the start of the ID line + const fallbackContentLines = fallbackListLines.slice( + 0, + fallbackListLines.length - 1 + ); + const fallbackContentText = fallbackContentLines.join('\n'); + const fallbackIdLine = + fallbackListLines[fallbackListLines.length - 1]; + const fallbackListContentEndOffset = + node.position!.start.offset! + fallbackContentText.length; + const fallbackListIdStartOffset = + node.position!.end.offset! - fallbackIdLine.length; + let fallbackBetweenText = markdown.substring( + fallbackListContentEndOffset, + fallbackListIdStartOffset + ); + fallbackBetweenText = fallbackBetweenText.replace(/\r\n?/g, '\n'); + const fallbackHasEmptyLine = /\n\s*\n/.test(fallbackBetweenText); + const fallbackIsExactlyOneNewline = /^\n[ \t]*$/.test( + fallbackBetweenText + ); + // Block section creation if any blank line is present or if not exactly one newline + if (fallbackHasEmptyLine || !fallbackIsExactlyOneNewline) { + processedNodes.add(node); + return; + } + // Only create a section if there is exactly one newline and node is not processed + if (fallbackIsExactlyOneNewline && !processedNodes.has(node)) { + // Create section for the entire list + const sectionLabel = fallbackContentText; + const sectionId = fallbackLastLine.trim().substring(1); + const startPos = astPointToFoamPosition(node.position!.start); + const endLine = startPos.line + fallbackContentLines.length - 1; + let endChar = + fallbackContentLines[fallbackContentLines.length - 1].length; + const sectionRange = Range.create( + startPos.line, + startPos.character, + endLine, + endChar + ); + const blockSection: BlockSection = { + type: 'block', + id: sectionId, + blockId: fallbackLastLine.trim(), + label: sectionLabel, + range: sectionRange, + }; + note.sections.push(blockSection); + processedNodes.add(node); + } + } + // Otherwise, do nothing (do not create a section) + return; + } + + let block: Node | undefined; + let blockId: string | undefined; + let idNode: Node | undefined; // The node containing the full-line ID, if applicable + + const nodeText = getNodeText(node, markdown); + + // If this node is a listItem and is processed, skip all section creation + if (node.type === 'listItem' && processedNodes.has(node)) { + return; + } + + // Case 1: Check for a full-line block ID (applies an ID from a separate line to the immediately preceding node) + if (node.type === 'paragraph' && index > 0) { + const pText = nodeText.trim(); + const isFullLineIdParagraph = /^\s*(\^[:\w.-]+\s*)+$/.test(pText); + + if (isFullLineIdParagraph) { + const fullLineBlockId = getLastBlockId(pText); + const previousSibling = parent.children[index - 1]; + + // Use AST line numbers and text between to check for exactly one newline (no empty line) between block and ID + const prevEndLine = previousSibling.position!.end.line; + const idStartLine = node.position!.start.line; + let betweenText = markdown.substring( + previousSibling.position!.end.offset, + node.position!.start.offset + ); + // Normalize: allow a single newline with optional trailing whitespace, but block if any blank line (\n\s*\n) is present + betweenText = betweenText.replace(/\r\n?/g, '\n'); + const hasEmptyLine = /\n\s*\n/.test(betweenText); + const isExactlyOneNewline = /^\n[ \t]*$/.test(betweenText); + + if ( + isExactlyOneNewline && + !hasEmptyLine && + !processedNodes.has(previousSibling) + ) { + block = previousSibling; + blockId = fullLineBlockId; + idNode = node; // Mark this paragraph as the ID provider. + } else { + // This is an unlinked ID paragraph; mark it and the previousSibling (block node) and all its children as processed and skip. + processedNodes.add(node); + // Mark previousSibling and all its children as processed + const markAllChildren = n => { + processedNodes.add(n); + if (n.children && Array.isArray(n.children)) { + n.children.forEach(markAllChildren); + } + }; + markAllChildren(previousSibling); + return; + } + } + } + + // Case 2: Check for an inline block ID if a full-line ID was not found (finds an ID at the end of the text within the current node) + if (!block) { + // Skip text nodes - only process container nodes like paragraph, listItem, etc. + if (node.type === 'text') { + return; + } + let textForInlineId = nodeText; + // For list items, only the first line can contain an inline ID for the whole item. + if (node.type === 'listItem') { + textForInlineId = nodeText.split(/\r?\n/)[0]; + } + const inlineBlockId = getLastBlockId(textForInlineId); + if (inlineBlockId) { + // An ID in the first paragraph of a list item applies to the entire item. + if (node.type === 'paragraph' && parent.type === 'listItem') { + if (parent.children[0] === node) { + processedNodes.add(parent); // Mark parent to avoid reprocessing children. + block = parent; + } else { + // The ID applies only to this paragraph, not the whole list item. + block = node; + } + } else { + block = node; + } + blockId = inlineBlockId; + } + } + + // If a block and ID were found, create a new section for it. + if (block && blockId) { + // If the block is processed, skip section creation + if (processedNodes.has(block)) { + return; + } + // Special handling for lists: check for blank lines after the list and before a block ID paragraph + if (block.type === 'list') { + const parent = ancestors[ancestors.length - 1] as any; + if (parent && parent.children) { + const blockIndex = parent.children.indexOf(block); + if (blockIndex !== -1 && blockIndex + 1 < parent.children.length) { + const nextSibling = parent.children[blockIndex + 1]; + if (nextSibling && nextSibling.type === 'paragraph') { + const nextText = getNodeText(nextSibling, markdown).trim(); + if (/^\s*(\^[:\w.-]+\s*)+$/.test(nextText)) { + const blockEndLine = block.position!.end.line; + const idStartLine = nextSibling.position!.start.line; + const lines = markdown.split('\n'); + let hasBlankLine = false; + for (let i = blockEndLine - 1; i < idStartLine - 1; i++) { + if (i >= 0 && i < lines.length) { + const line = lines[i]; + if (line.trim() === '') { + hasBlankLine = true; + break; + } + } + } + if (hasBlankLine) { + processedNodes.add(nextSibling); + return; + } + } + } + } + } + } + let sectionLabel: string; + let sectionId: string; + let sectionRange: Range; + let fudge = undefined; + switch (block.type) { + case 'listItem': { + let raw = getNodeText(block, markdown); + let lines = raw.split('\n'); + if ( + lines.length > 1 && + /^\s*(\^[\w.-]+\s*)+$/.test(lines[lines.length - 1].trim()) + ) { + lines = lines.slice(0, -1); + } + sectionLabel = lines.join('\n'); + sectionId = blockId.substring(1); + fudge = { + childListId: /child-list-id\s*$/.test(sectionLabel), + parentListId: /parent-list-id/.test(sectionLabel), + fullListId: /full-list-id/.test(markdown), + }; + sectionRange = calculateSectionRange( + block, + sectionLabel, + markdown, + fudge + ); + break; + } + case 'list': { + const { label, id } = extractLabelAndBlockId( + block, + markdown, + blockId, + idNode + ); + sectionLabel = label; + sectionId = id; + sectionRange = calculateSectionRange(block, sectionLabel, markdown); + break; + } + case 'table': + case 'code': { + sectionLabel = getNodeText(block, markdown); + sectionId = blockId.substring(1); + const startPos = astPointToFoamPosition(block.position!.start); + const lines = sectionLabel.split('\n'); + const endPos = Position.create( + startPos.line + lines.length - 1, + lines[lines.length - 1].length + ); + sectionRange = Range.create( + startPos.line, + startPos.character, + endPos.line, + endPos.character + ); + break; + } + case 'blockquote': { + const rawText = getNodeText(block, markdown); + const lines = rawText.split('\n'); + lines.pop(); + sectionLabel = lines.join('\n'); + sectionId = blockId.substring(1); + const startPos = astPointToFoamPosition(block.position!.start); + const lastLine = lines[lines.length - 1]; + const endPos = Position.create( + startPos.line + lines.length - 1, + lastLine.length - 1 + ); + sectionRange = Range.create( + startPos.line, + startPos.character, + endPos.line, + endPos.character + ); + break; + } + case 'paragraph': + default: { + sectionLabel = getNodeText(block, markdown); + sectionId = blockId.substring(1); + const startPos = astPointToFoamPosition(block.position!.start); + const lines = sectionLabel.split('\n'); + const endPos = Position.create( + startPos.line + lines.length - 1, + lines[lines.length - 1].length + ); + sectionRange = Range.create( + startPos.line, + startPos.character, + endPos.line, + endPos.character + ); + break; + } + } + const sectionObj: BlockSection = { + id: sectionId, + blockId: blockId!, + label: sectionLabel, + range: sectionRange, + type: 'block', + }; + note.sections.push(sectionObj); + // Mark the nodes as processed to prevent duplicates. + processedNodes.add(block); + if (idNode) { + processedNodes.add(idNode); + } + // Skip visiting children of an already-processed block for efficiency. + if (block.type === 'listItem') { + visit(block as any, (child: any) => { + processedNodes.add(child); + }); + return visit.SKIP; + } + return visit.SKIP; + } + }, + }; }; -/** - * Converts the 1-index Position object into the VS Code 0-index Range object - * @param position an ast Position object (1-indexed) - * @returns Foam Range (0-indexed) - */ -const astPositionToFoamRange = (pos: AstPosition): Range => - Range.create( - pos.start.line - 1, - pos.start.column - 1, - pos.end.line - 1, - pos.end.column - 1 - ); +// Core parser logic: creates a markdown parser with all plugins and optional cache. -const blockParser = unified().use(markdownParse, { gfm: true }); -export const getBlockFor = ( - markdown: string, - line: number | Position -): { block: string; nLines: number } => { - const searchLine = typeof line === 'number' ? line : line.line; - const tree = blockParser.parse(markdown); - const lines = markdown.split('\n'); - let startLine = -1; - let endLine = -1; - - // For list items, we also include the sub-lists - visit(tree, ['listItem'], (node: any) => { - if (node.position.start.line === searchLine + 1) { - startLine = node.position.start.line - 1; - endLine = node.position.end.line; - return visit.EXIT; - } - }); +export function createMarkdownParser( + extraPlugins: ParserPlugin[] = [], + cache?: ParserCache +): ResourceParser { + const parser = unified() + .use(markdownParse, { gfm: true }) + .use(frontmatterPlugin, ['yaml']) + .use(wikiLinkPlugin, { aliasDivider: '|' }); - // For headings, we also include the sub-sections - let headingLevel = -1; - visit(tree, ['heading'], (node: any) => { - if (startLine > -1 && node.depth <= headingLevel) { - endLine = node.position.start.line - 1; - return visit.EXIT; - } - if (node.position.start.line === searchLine + 1) { - headingLevel = node.depth; - startLine = node.position.start.line - 1; - endLine = lines.length - 1; // in case it's the last section + const plugins = [ + titlePlugin, + wikilinkPlugin, + definitionsPlugin, + tagsPlugin, + aliasesPlugin, + sectionsPlugin, + createBlockIdPlugin(), + ...extraPlugins, + ]; + + for (const plugin of plugins) { + try { + plugin.onDidInitializeParser?.(parser); + } catch (e) { + handleError(plugin, 'onDidInitializeParser', undefined, e); } - }); + } + + const actualParser: ResourceParser = { + parse: (uri: URI, markdown: string): Resource => { + Logger.debug('Parsing:', uri.toString()); + for (const plugin of plugins) { + try { + plugin.onWillParseMarkdown?.(markdown); + } catch (e) { + handleError(plugin, 'onWillParseMarkdown', uri, e); + } + } + const tree = parser.parse(markdown); + + const note: Resource = { + uri: uri, + type: 'note', + properties: {}, + title: '', + sections: [], + tags: [], + aliases: [], + links: [], + definitions: [], + }; + + for (const plugin of plugins) { + try { + plugin.onWillVisitTree?.(tree, note); + } catch (e) { + handleError(plugin, 'onWillVisitTree', uri, e); + } + } + visitWithAncestors(tree, (node, ancestors) => { + // Use visitWithAncestors to get the parent of the current node. + const parent = ancestors[ancestors.length - 1] as Parent | undefined; + const index = parent ? parent.children.indexOf(node) : undefined; + + if (node.type === 'yaml') { + try { + const yamlProperties = parseYAML((node as any).value) ?? {}; + note.properties = { + ...note.properties, + ...yamlProperties, + }; + for (const plugin of plugins) { + try { + plugin.onDidFindProperties?.(yamlProperties, note, node); + } catch (e) { + handleError(plugin, 'onDidFindProperties', uri, e); + } + } + } catch (e) { + Logger.warn(`Error while parsing YAML for [${uri.toString()}]`, e); + } + } + + for (const plugin of plugins) { + try { + plugin.visit?.(node, note, markdown, index, parent, ancestors); + } catch (e) { + handleError(plugin, 'visit', uri, e); + } + } + }); + for (const plugin of plugins) { + try { + plugin.onDidVisitTree?.(tree, note, markdown); + } catch (e) { + handleError(plugin, 'onDidVisitTree', uri, e); + } + } + Logger.debug('Result:', note); + return note; + }, + }; + + const cachedParser: ResourceParser = { + parse: (uri: URI, markdown: string): Resource => { + const actualChecksum = hash(markdown); + if (cache.has(uri)) { + const { checksum, resource } = cache.get(uri); + if (actualChecksum === checksum) { + return resource; + } + } + const resource = actualParser.parse(uri, markdown); + cache.set(uri, { checksum: actualChecksum, resource }); + return resource; + }, + }; - let nLines = startLine === -1 ? 1 : endLine - startLine; - let block = - startLine === -1 - ? lines[searchLine] ?? '' - : lines.slice(startLine, endLine).join('\n'); + return isSome(cache) ? cachedParser : actualParser; +} - return { block, nLines }; +// Returns concatenated text from all children of a node (used for headings and titles). +const getTextFromChildren = (root: Node): string => { + let text = ''; + visit(root as any, (node: any) => { + if ( + node.type === 'text' || + node.type === 'wikiLink' || + node.type === 'code' || + node.type === 'html' + ) { + text = text + (node.value || ''); + } + }); + return text; }; diff --git a/packages/foam-vscode/src/core/services/markdown-provider.ts b/packages/foam-vscode/src/core/services/markdown-provider.ts index 522003b27..ff91b99ef 100644 --- a/packages/foam-vscode/src/core/services/markdown-provider.ts +++ b/packages/foam-vscode/src/core/services/markdown-provider.ts @@ -35,7 +35,7 @@ export class MarkdownResourceProvider implements ResourceProvider { if (isSome(section)) { const rows = content.split('\n'); content = rows - .slice(section.range.start.line, section.range.end.line) + .slice(section.range.start.line, section.range.end.line + 1) .join('\n'); } } diff --git a/packages/foam-vscode/src/core/utils/links.ts b/packages/foam-vscode/src/core/utils/links.ts new file mode 100644 index 000000000..d98784405 --- /dev/null +++ b/packages/foam-vscode/src/core/utils/links.ts @@ -0,0 +1,12 @@ +/** + * Parses a wikilink target into its note and fragment components. + * @param wikilinkTarget The full string target of the wikilink (e.g., 'my-note#my-heading'). + * @returns An object containing the noteTarget and an optional fragment. + */ +export function parseWikilink(wikilinkTarget: string): { + noteTarget: string; + fragment?: string; +} { + const [noteTarget, fragment] = wikilinkTarget.split('#'); + return { noteTarget, fragment }; +} diff --git a/packages/foam-vscode/src/core/utils/md.ts b/packages/foam-vscode/src/core/utils/md.ts index 261e86757..361288ab8 100644 --- a/packages/foam-vscode/src/core/utils/md.ts +++ b/packages/foam-vscode/src/core/utils/md.ts @@ -1,4 +1,12 @@ import matter from 'gray-matter'; +import { Position } from '../model/position'; // Add Position import to the top + +/** + * Gets the raw text of a node from the source markdown. + * @param node The AST node with position info. + * @param markdown The full markdown source string. + * @returns The raw text corresponding to the node. + */ export function getExcerpt( markdown: string, @@ -68,3 +76,29 @@ export function isOnYAMLKeywordLine(content: string, keyword: string): boolean { const lastMatch = matches[matches.length - 1]; return lastMatch[1] === keyword; } + +/** + * Extracts a contiguous block of non-empty lines from a Markdown string. + * + * @param markdown The full Markdown string to extract from. + * @param position The starting position (line number) for the extraction. + * @returns An object containing: + * - `block`: The extracted string content of the block. + * - `nLines`: The total number of lines in the extracted block. This + * is calculated as `blockEnd - blockStart + 1`, which is crucial + * for consumers to know the exact range of the block. + */ +export function getBlockFor( + markdown: string, + position: Position +): { block: string; nLines: number } { + const lines = markdown.split('\n'); + const blockStart = position.line; + let blockEnd = blockStart; + while (blockEnd < lines.length - 1 && lines[blockEnd + 1].trim() !== '') { + blockEnd++; + } + const block = lines.slice(blockStart, blockEnd + 1).join('\n'); + const nLines = blockEnd - blockStart + 1; + return { block, nLines }; +} diff --git a/packages/foam-vscode/src/core/utils/visit-with-ancestors.ts b/packages/foam-vscode/src/core/utils/visit-with-ancestors.ts new file mode 100644 index 000000000..23d4b50c6 --- /dev/null +++ b/packages/foam-vscode/src/core/utils/visit-with-ancestors.ts @@ -0,0 +1,50 @@ +import { Node } from 'unist'; +import visit from 'unist-util-visit'; + +/** + * A shim function that replicates the behavior of unist-util-visit-parents + * by manually tracking ancestors and providing them to the visitor function. + * + * This allows existing parsing logic that expects the `ancestors` array + * to function correctly with `unist-util-visit`. + * + * @param tree The root of the AST to traverse. + * @param visitor The function to call for each node, with signature (node, ancestors). + * It can return `visit.SKIP` (symbol) or the string 'skip' to stop traversing children. + */ +export function visitWithAncestors( + tree: Node, + visitor: (node: Node, ancestors: Node[]) => void | symbol | 'skip' +) { + const ancestors: Node[] = []; + + (visit as any)(tree, (node: any, index: number, parent: any) => { + // Maintain the ancestors stack + // When we visit a node, its parent is the last element added to the stack. + // If the current node is not a child of the last ancestor, it means we've + // moved to a sibling or a new branch, so we need to pop ancestors until + // the current parent is at the top of the stack. + while (ancestors.length > 0 && ancestors[ancestors.length - 1] !== parent) { + ancestors.pop(); + } + + // Add the current node's parent to the ancestors stack if it's not already there + if (parent && ancestors[ancestors.length - 1] !== parent) { + ancestors.push(parent); + } + + // Call the original visitor with the node and the current ancestors stack + const result = visitor(node, [...ancestors]); // Pass a copy to prevent external modification + + // If the visitor returns visit.SKIP (symbol) or 'skip' (string), propagate it to unist-util-visit + if ( + result === visit.SKIP || + (typeof result === 'string' && result === 'skip') + ) { + return visit.SKIP; + } + + // Push the current node onto the stack for its children + ancestors.push(node); + }); +} diff --git a/packages/foam-vscode/src/dated-notes.spec.ts b/packages/foam-vscode/src/dated-notes.spec.ts index c795a52c1..0ada5c9ce 100644 --- a/packages/foam-vscode/src/dated-notes.spec.ts +++ b/packages/foam-vscode/src/dated-notes.spec.ts @@ -1,16 +1,26 @@ -import { workspace } from 'vscode'; -import { createDailyNoteIfNotExists, getDailyNoteUri } from './dated-notes'; +/* @unit-ready */ +import { workspace, window } from 'vscode'; +import { + CREATE_DAILY_NOTE_WARNING_RESPONSE, + createDailyNoteIfNotExists, + getDailyNoteUri, +} from './dated-notes'; import { isWindows } from './core/common/platform'; import { cleanWorkspace, closeEditors, createFile, deleteFile, + getUriInWorkspace, showInEditor, withModifiedFoamConfiguration, } from './test/test-utils-vscode'; import { fromVsCodeUri } from './utils/vsc-utils'; -import { URI } from './core/model/uri'; +import { fileExists, readFile } from './services/editor'; +import { + getDailyNoteTemplateCandidateUris, + getDailyNoteTemplateUri, +} from './services/templates'; describe('getDailyNoteUri', () => { const date = new Date('2021-02-07T00:00:00Z'); @@ -45,25 +55,290 @@ describe('getDailyNoteUri', () => { }); }); -describe('Daily note template', () => { - it('Uses the daily note variables in the template', async () => { - const targetDate = new Date(2021, 8, 12); +describe('Daily note creation and template processing', () => { + const DAILY_NOTE_TEMPLATE = ['.foam', 'templates', 'daily-note.md']; - const template = await createFile( - // eslint-disable-next-line no-template-curly-in-string - 'hello ${FOAM_DATE_MONTH_NAME} ${FOAM_DATE_DATE} hello', - ['.foam', 'templates', 'daily-note.md'] - ); + beforeEach(async () => { + // Ensure daily note template are removed before each test + for (const template of getDailyNoteTemplateCandidateUris()) { + if (await fileExists(template)) { + await deleteFile(template); + } + } + }); + + describe('Basic daily note creation', () => { + it('Creates a new daily note when it does not exist', async () => { + const targetDate = new Date(2021, 8, 1); + const uri = getDailyNoteUri(targetDate); + const foam = {} as any; // Mock Foam instance + + const result = await createDailyNoteIfNotExists(targetDate, foam); + + expect(result.didCreateFile).toBe(true); + expect(result.uri).toEqual(uri); + + const doc = await showInEditor(uri); + expect(doc.editor.document.getText()).toContain('2021-09-01'); + }); + + it('Opens existing daily note when it already exists', async () => { + const targetDate = new Date(2021, 8, 2); + const uri = getDailyNoteUri(targetDate); + const foam = {} as any; // Mock Foam instance + + // Create the file first + await createFile('# Existing Note\n\nContent here', [uri.getBasename()]); + + const result = await createDailyNoteIfNotExists(targetDate, foam); + + expect(result.didCreateFile).toBe(false); + expect(result.uri).toEqual(uri); + + const doc = await showInEditor(uri); + expect(doc.editor.document.getText()).toContain('Existing Note'); + }); + }); + + describe('Template variable resolution', () => { + it('Resolves all FOAM_DATE_* variables correctly', async () => { + const targetDate = new Date(2021, 8, 12); // September 12, 2021 + + const template = await createFile( + // eslint-disable-next-line no-template-curly-in-string + `# \${FOAM_DATE_YEAR}-\${FOAM_DATE_MONTH}-\${FOAM_DATE_DATE} + +Year: \${FOAM_DATE_YEAR} (short: \${FOAM_DATE_YEAR_SHORT}) +Month: \${FOAM_DATE_MONTH} (name: \${FOAM_DATE_MONTH_NAME}, short: \${FOAM_DATE_MONTH_NAME_SHORT}) +Date: \${FOAM_DATE_DATE} +Day: \${FOAM_DATE_DAY_NAME} (short: \${FOAM_DATE_DAY_NAME_SHORT}) +Week: \${FOAM_DATE_WEEK} +Unix: \${FOAM_DATE_SECONDS_UNIX}`, + DAILY_NOTE_TEMPLATE + ); + + const foam = {} as any; // Mock Foam instance + const result = await createDailyNoteIfNotExists(targetDate, foam); + + const doc = await showInEditor(result.uri); + const content = doc.editor.document.getText(); + + expect(content).toContain('# 2021-09-12'); + expect(content).toContain('Year: 2021 (short: 21)'); + expect(content).toContain('Month: 09 (name: September, short: Sep)'); + expect(content).toContain('Date: 12'); + expect(content).toContain('Day: Sunday (short: Sun)'); + expect(content).toContain('Week: 36'); + + await deleteFile(template.uri); + await deleteFile(result.uri); + }); + + it('Resolves FOAM_TITLE variable for daily notes', async () => { + const targetDate = new Date(2021, 8, 13); + + const template = await createFile( + // eslint-disable-next-line no-template-curly-in-string + '# Daily Note: ${FOAM_TITLE}\n\nToday is ${FOAM_TITLE}.', + DAILY_NOTE_TEMPLATE + ); + + const uri = getDailyNoteUri(targetDate); + const foam = {} as any; // Mock Foam instance + const result = await createDailyNoteIfNotExists(targetDate, foam); + + const doc = await showInEditor(uri); + const content = doc.editor.document.getText(); + expect(content).toContain('Daily Note: 2021-09-13'); + expect(content).toContain('Today is 2021-09-13.'); + await deleteFile(result.uri); + await deleteFile(template.uri); + }); + }); + + describe('Configuration settings', () => { + it('Respects custom filename format', async () => { + const targetDate = new Date(2021, 8, 14); + const customFormat = 'yyyy-mm-dd'; + + await withModifiedFoamConfiguration( + 'openDailyNote.filenameFormat', + customFormat, + async () => { + const uri = getDailyNoteUri(targetDate); + expect(uri.getBasename()).toBe('2021-09-14.md'); + } + ); + }); + + it('Respects custom file extension', async () => { + const targetDate = new Date(2021, 8, 15); + + await withModifiedFoamConfiguration( + 'openDailyNote.fileExtension', + 'txt', + async () => { + const uri = getDailyNoteUri(targetDate); + expect(uri.getBasename()).toBe('2021-09-15.txt'); + } + ); + }); + + it('Respects custom directory setting', async () => { + const targetDate = new Date(2021, 8, 16); + const customDir = 'journal/daily'; + + await withModifiedFoamConfiguration( + 'openDailyNote.directory', + customDir, + async () => { + const uri = getDailyNoteUri(targetDate); + expect(uri.path).toContain('/journal/daily/'); + } + ); + }); + + it('Uses custom title format when specified', async () => { + const targetDate = new Date(2021, 8, 17); + + await withModifiedFoamConfiguration( + 'openDailyNote.titleFormat', + 'fullDate', + async () => { + const uri = getDailyNoteUri(targetDate); + const foam = {} as any; // Mock Foam instance + const result = await createDailyNoteIfNotExists(targetDate, foam); + + const doc = await showInEditor(uri); + const content = doc.editor.document.getText(); + expect(content).toContain('# Friday, September 17, 2021'); + await deleteFile(result.uri); + } + ); + }); + }); + + describe('Template types and processing', () => { + it('Processes Markdown templates correctly', async () => { + const targetDate = new Date(2021, 8, 19); + + const template = await createFile( + // eslint-disable-next-line no-template-curly-in-string + 'hello ${FOAM_DATE_MONTH_NAME} ${FOAM_DATE_DATE} hello', + DAILY_NOTE_TEMPLATE + ); + + const uri = getDailyNoteUri(targetDate); + const foam = {} as any; // Mock Foam instance + const result = await createDailyNoteIfNotExists(targetDate, foam); + + const doc = await showInEditor(uri); + const content = doc.editor.document.getText(); + expect(content).toEqual('hello September 19 hello'); + await deleteFile(result.uri); + await deleteFile(template.uri); + }); + + it('Processes JavaScript templates correctly', async () => { + const targetDate = new Date(2021, 8, 20); + + const jsTemplate = await createFile( + `async function createNote ({ foamDate }) { + const monthName = foamDate.toLocaleString('default', { month: 'long' }); + const day = foamDate.getDate(); + return { + filepath: \`\${foamDate.getFullYear()}-\${String(foamDate.getMonth() + 1).padStart(2, '0')}-\${String(day).padStart(2, '0')}.md\`, + content: \`# JS Template: \${monthName} \${day}\n\nGenerated by JavaScript template.\` + }; +};`, + ['.foam', 'templates', 'daily-note.js'] + ); + + const uri = getDailyNoteUri(targetDate); + const foam = {} as any; // Mock Foam instance + const result = await createDailyNoteIfNotExists(targetDate, foam); + + const doc = await showInEditor(uri); + const content = doc.editor.document.getText(); + expect(content).toContain('# JS Template: September 20'); + expect(content).toContain('Generated by JavaScript template.'); + + await deleteFile(jsTemplate.uri); + await deleteFile(result.uri); + }); + + it('Falls back to default text when no template exists', async () => { + const targetDate = new Date(2021, 8, 21); + const foam = {} as any; // Mock Foam instance + const result = await createDailyNoteIfNotExists(targetDate, foam); + + const doc = await showInEditor(result.uri); + const content = doc.editor.document.getText(); + expect(content).toContain('# 2021-09-21'); // Should use fallback text with formatted date + }); + + it('prompts to create a daily note template if one does not exist', async () => { + const targetDate = new Date(2021, 8, 23); + const foam = {} as any; + + expect(await getDailyNoteTemplateUri()).not.toBeDefined(); + + // Intercept the showWarningMessage call + const showWarningMessageSpy = jest + .spyOn(window, 'showWarningMessage') + .mockResolvedValue(CREATE_DAILY_NOTE_WARNING_RESPONSE as any); // simulate user action + + await createDailyNoteIfNotExists(targetDate, foam); + + expect(showWarningMessageSpy.mock.calls[0][0]).toMatch( + /No daily note template found/ + ); + + const templateUri = await getDailyNoteTemplateUri(); + + expect(templateUri).toBeDefined(); + expect(await fileExists(templateUri)).toBe(true); + + const templateContent = await readFile(templateUri); + expect(templateContent).toContain('foam_template:'); + + // Clean up the created template + await deleteFile(templateUri); + showWarningMessageSpy.mockRestore(); + }); + + it('Processes template frontmatter metadata correctly', async () => { + const targetDate = new Date(2021, 8, 22); + + const template = await createFile( + `--- +tags: [daily, journal] +author: foam +--- +# Daily Note + +Content here with \${FOAM_DATE_MONTH_NAME} \${FOAM_DATE_DATE}`, + DAILY_NOTE_TEMPLATE + ); - const uri = getDailyNoteUri(targetDate); + const uri = getDailyNoteUri(targetDate); + const foam = {} as any; // Mock Foam instance + const result = await createDailyNoteIfNotExists(targetDate, foam); - await createDailyNoteIfNotExists(targetDate); + const doc = await showInEditor(uri); + const content = doc.editor.document.getText(); - const doc = await showInEditor(uri); - const content = doc.editor.document.getText(); - expect(content).toEqual('hello September 12 hello'); + // Should not contain the frontmatter separator in final content + expect(content).toContain(`--- +tags: [daily, journal] +author: foam +---`); + expect(content).toContain('# Daily Note'); + expect(content).toContain('Content here with September 22'); - await deleteFile(template.uri); + await deleteFile(template.uri); + await deleteFile(result.uri); + }); }); afterAll(async () => { diff --git a/packages/foam-vscode/src/dated-notes.ts b/packages/foam-vscode/src/dated-notes.ts index cd495fd2d..441fd427e 100644 --- a/packages/foam-vscode/src/dated-notes.ts +++ b/packages/foam-vscode/src/dated-notes.ts @@ -1,9 +1,17 @@ +import { Uri, window, workspace } from 'vscode'; import { joinPath } from './core/utils/path'; import dateFormat from 'dateformat'; import { URI } from './core/model/uri'; -import { NoteFactory } from './services/templates'; +import { getDailyNoteTemplateUri } from './services/templates'; import { getFoamVsCodeConfig } from './services/config'; import { asAbsoluteWorkspaceUri, focusNote } from './services/editor'; +import { Foam } from './core/model/foam'; +import { + CREATE_NOTE_COMMAND, + createNote, +} from './features/commands/create-note'; +import { fromVsCodeUri } from './utils/vsc-utils'; +import { showInEditor } from './test/test-utils-vscode'; /** * Open the daily note file. @@ -12,13 +20,14 @@ import { asAbsoluteWorkspaceUri, focusNote } from './services/editor'; * it gets created along with any folders in its path. * * @param date The target date. If not provided, the function returns immediately. + * @param foam The Foam instance, used to create the note. */ -export async function openDailyNoteFor(date?: Date) { +export async function openDailyNoteFor(date?: Date, foam?: Foam) { if (date == null) { return; } - const { didCreateFile, uri } = await createDailyNoteIfNotExists(date); + const { didCreateFile, uri } = await createDailyNoteIfNotExists(date, foam); // if a new file is created, the editor is automatically created // but forcing the focus will block the template placeholders from working // so we only explicitly focus on the note if the file already exists @@ -54,30 +63,86 @@ export function getDailyNoteUri(date: Date): URI { */ export function getDailyNoteFileName(date: Date): string { const filenameFormat: string = getFoamVsCodeConfig( - 'openDailyNote.filenameFormat' + 'openDailyNote.filenameFormat', + 'yyyy-mm-dd' ); const fileExtension: string = getFoamVsCodeConfig( - 'openDailyNote.fileExtension' + 'openDailyNote.fileExtension', + 'md' ); return `${dateFormat(date, filenameFormat, false)}.${fileExtension}`; } +const DEFAULT_DAILY_NOTE_TEMPLATE = `--- +foam_template: + filepath: "/journal/\${FOAM_DATE_YEAR}-\${FOAM_DATE_MONTH}-\${FOAM_DATE_DATE}.md" + description: "Daily note template" +--- +# \${FOAM_DATE_YEAR}-\${FOAM_DATE_MONTH}-\${FOAM_DATE_DATE} + +> you probably want to delete these instructions as you customize your template + +Welcome to your new daily note template. +The file is located in \`.foam/templates/daily-note.md\`. +The text in this file will be used as the content of your daily note. +You can customize it as you like, and you can use the following variables in the template: +- \`\${FOAM_DATE_YEAR}\`: The year of the date +- \`\${FOAM_DATE_MONTH}\`: The month of the date +- \`\${FOAM_DATE_DATE}\`: The day of the date +- \`\${FOAM_TITLE}\`: The title of the note + +Go to https://github.com/foambubble/foam/blob/main/docs/user/features/daily-notes.md for more details. +For more complex templates, including Javascript dynamic templates, see https://github.com/foambubble/foam/blob/main/docs/user/features/note-templates.md. +`; + +export const CREATE_DAILY_NOTE_WARNING_RESPONSE = 'Create daily note template'; + /** - * Create a daily note if it does not exist. + * Create a daily note using the unified creation engine (supports JS templates) * - * In the case that the folders referenced in the file path also do not exist, - * this function will create all folders in the path. - * - * @param currentDate The current date, to be used as a title. - * @returns Whether the file was created. + * @param targetDate The target date + * @param foam The Foam instance + * @returns Whether the file was created and the URI */ -export async function createDailyNoteIfNotExists(targetDate: Date) { - const uriFromLegacyConfiguration = getDailyNoteUri(targetDate); - const pathFromLegacyConfiguration = uriFromLegacyConfiguration.toFsPath(); +export async function createDailyNoteIfNotExists(targetDate: Date, foam: Foam) { + const templatePath = await getDailyNoteTemplateUri(); + + if (!templatePath) { + window + .showWarningMessage( + 'No daily note template found. Using legacy configuration (deprecated). Create a daily note template to avoid this warning and customize your daily note.', + CREATE_DAILY_NOTE_WARNING_RESPONSE + ) + .then(async action => { + if (action === CREATE_DAILY_NOTE_WARNING_RESPONSE) { + const newTemplateUri = Uri.joinPath( + workspace.workspaceFolders[0].uri, + '.foam', + 'templates', + 'daily-note.md' + ); + await workspace.fs.writeFile( + newTemplateUri, + new TextEncoder().encode(DEFAULT_DAILY_NOTE_TEMPLATE) + ); + await showInEditor(fromVsCodeUri(newTemplateUri)); + } + }); + } + + // Set up variables for template processing + const formattedDate = dateFormat(targetDate, 'yyyy-mm-dd', false); + const variables = { + FOAM_TITLE: formattedDate, + title: formattedDate, + }; + + const dailyNoteUri = getDailyNoteUri(targetDate); const titleFormat: string = getFoamVsCodeConfig('openDailyNote.titleFormat') ?? - getFoamVsCodeConfig('openDailyNote.filenameFormat'); + getFoamVsCodeConfig('openDailyNote.filenameFormat') ?? + 'isoDate'; const templateFallbackText = `# ${dateFormat( targetDate, @@ -85,9 +150,16 @@ export async function createDailyNoteIfNotExists(targetDate: Date) { false )}\n`; - return await NoteFactory.createFromDailyNoteTemplate( - uriFromLegacyConfiguration, - templateFallbackText, - targetDate + return await createNote( + { + notePath: dailyNoteUri.toFsPath(), + templatePath: templatePath, + text: templateFallbackText, + date: targetDate, + variables: variables, + onFileExists: 'open', + onRelativeNotePath: 'resolve-from-root', + }, + foam ); } diff --git a/packages/foam-vscode/src/extension.ts b/packages/foam-vscode/src/extension.ts index f27bdf604..9bb2f03e6 100644 --- a/packages/foam-vscode/src/extension.ts +++ b/packages/foam-vscode/src/extension.ts @@ -86,7 +86,10 @@ export async function activate(context: ExtensionContext) { attachmentProvider, commands.registerCommand('foam-vscode.clear-cache', () => parserCache.clear() - ), + ) + ); + + context.subscriptions.push( workspace.onDidChangeConfiguration(e => { if ( [ diff --git a/packages/foam-vscode/src/features/commands/copy-without-brackets.spec.ts b/packages/foam-vscode/src/features/commands/copy-without-brackets.spec.ts index 398b5445c..0f26f586c 100644 --- a/packages/foam-vscode/src/features/commands/copy-without-brackets.spec.ts +++ b/packages/foam-vscode/src/features/commands/copy-without-brackets.spec.ts @@ -1,3 +1,4 @@ +/* @unit-ready */ import { env, Position, Selection, commands } from 'vscode'; import { createFile, showInEditor } from '../../test/test-utils-vscode'; import { removeBrackets, toTitleCase } from './copy-without-brackets'; diff --git a/packages/foam-vscode/src/features/commands/create-note-from-template.spec.ts b/packages/foam-vscode/src/features/commands/create-note-from-template.spec.ts index 336117eb0..303ea21dd 100644 --- a/packages/foam-vscode/src/features/commands/create-note-from-template.spec.ts +++ b/packages/foam-vscode/src/features/commands/create-note-from-template.spec.ts @@ -1,3 +1,4 @@ +/* @unit-ready */ import { commands, window, workspace } from 'vscode'; import { toVsCodeUri } from '../../utils/vsc-utils'; import { createFile } from '../../test/test-utils-vscode'; diff --git a/packages/foam-vscode/src/features/commands/create-note-from-template.ts b/packages/foam-vscode/src/features/commands/create-note-from-template.ts index b058a719a..5bba42c31 100644 --- a/packages/foam-vscode/src/features/commands/create-note-from-template.ts +++ b/packages/foam-vscode/src/features/commands/create-note-from-template.ts @@ -1,19 +1,14 @@ import { commands, ExtensionContext } from 'vscode'; -import { askUserForTemplate, NoteFactory } from '../../services/templates'; -import { Resolver } from '../../services/variable-resolver'; +import { askUserForTemplate } from '../../services/templates'; export default async function activate(context: ExtensionContext) { context.subscriptions.push( commands.registerCommand( 'foam-vscode.create-note-from-template', async () => { - const templateUri = await askUserForTemplate(); - - if (templateUri) { - const resolver = new Resolver(new Map(), new Date()); - - await NoteFactory.createFromTemplate(templateUri, resolver); - } + await commands.executeCommand('foam-vscode.create-note', { + askForTemplate: true, + }); } ) ); diff --git a/packages/foam-vscode/src/features/commands/create-note.spec.ts b/packages/foam-vscode/src/features/commands/create-note.spec.ts index ca7993b8d..f61317575 100644 --- a/packages/foam-vscode/src/features/commands/create-note.spec.ts +++ b/packages/foam-vscode/src/features/commands/create-note.spec.ts @@ -1,3 +1,4 @@ +/* @unit-ready */ import { commands, window, workspace } from 'vscode'; import { URI } from '../../core/model/uri'; import { asAbsoluteWorkspaceUri, readFile } from '../../services/editor'; @@ -41,7 +42,7 @@ describe('create-note command', () => { ]); const target = getUriInWorkspace(); await commands.executeCommand('foam-vscode.create-note', { - notePath: target.path, + notePath: target, templatePath: templateA.uri.path, text: 'hello', }); @@ -54,7 +55,7 @@ describe('create-note command', () => { it('focuses on the newly created note', async () => { const target = getUriInWorkspace(); await commands.executeCommand('foam-vscode.create-note', { - notePath: target.path, + notePath: target, text: 'hello', }); expect(window.activeTextEditor.document.getText()).toEqual('hello'); @@ -65,7 +66,7 @@ describe('create-note command', () => { it('supports variables', async () => { const target = getUriInWorkspace(); await commands.executeCommand('foam-vscode.create-note', { - notePath: target.path, + notePath: target, text: 'hello ${FOAM_TITLE}', // eslint-disable-line no-template-curly-in-string variables: { FOAM_TITLE: 'world' }, }); @@ -77,7 +78,7 @@ describe('create-note command', () => { it('supports date variables', async () => { const target = getUriInWorkspace(); await commands.executeCommand('foam-vscode.create-note', { - notePath: target.path, + notePath: target, text: 'hello ${FOAM_DATE_YEAR}', // eslint-disable-line no-template-curly-in-string date: '2021-10-01', }); @@ -92,7 +93,7 @@ describe('create-note command', () => { expect(content).toEqual('hello'); await commands.executeCommand('foam-vscode.create-note', { - notePath: target.uri.path, + notePath: target.uri, text: 'test overwrite', onFileExists: 'overwrite', }); @@ -103,7 +104,7 @@ describe('create-note command', () => { await closeEditors(); await commands.executeCommand('foam-vscode.create-note', { - notePath: target.uri.path, + notePath: target.uri, text: 'test open', onFileExists: 'open', }); @@ -114,7 +115,7 @@ describe('create-note command', () => { await closeEditors(); await commands.executeCommand('foam-vscode.create-note', { - notePath: target.uri.path, + notePath: target.uri, text: 'test cancel', onFileExists: 'cancel', }); @@ -125,7 +126,7 @@ describe('create-note command', () => { .mockImplementationOnce(jest.fn(() => Promise.resolve(undefined))); await closeEditors(); await commands.executeCommand('foam-vscode.create-note', { - notePath: target.uri.path, + notePath: target.uri, text: 'test ask', onFileExists: 'ask', }); @@ -201,6 +202,54 @@ describe('create-note command', () => { // await deleteFile(base); }); + + it('throws an error if the template file does not exist', async () => { + const nonExistentTemplatePath = '/non/existent/template/path.md'; + await expect( + commands.executeCommand('foam-vscode.create-note', { + notePath: 'note-with-missing-template.md', + templatePath: nonExistentTemplatePath, + text: 'should not matter', + }) + ).rejects.toThrow( + `Failed to load template (file://${nonExistentTemplatePath}): Template file not found: file://${nonExistentTemplatePath}` + ); + }); + + it('throws an error if the template file does not exist (relative path)', async () => { + try { + const nonExistentTemplatePath = 'relative/non-existent-template.md'; + await commands.executeCommand('foam-vscode.create-note', { + notePath: 'note-with-missing-template-relative.md', + templatePath: nonExistentTemplatePath, + text: 'should not matter', + }); + throw new Error('Expected an error to be thrown'); + } catch (error) { + expect(error.message).toContain(`Failed to load template`); // eslint-disable-line jest/no-conditional-expect + } + }); + + it('creates a note with absolute path within the workspace', async () => { + await commands.executeCommand('foam-vscode.create-note', { + notePath: '/note-in-workspace.md', + text: 'hello workspace', + }); + expect(window.activeTextEditor.document.getText()).toEqual( + 'hello workspace' + ); + expectSameUri( + window.activeTextEditor.document.uri, + fromVsCodeUri(workspace.workspaceFolders?.[0].uri).joinPath( + 'note-in-workspace.md' + ) + ); + await deleteFile( + fromVsCodeUri(workspace.workspaceFolders?.[0].uri).joinPath( + 'note-in-workspace.md' + ) + ); + }); }); describe('factories', () => { @@ -251,7 +300,7 @@ foam_template: const results: Awaited> = await commands.executeCommand(command.name, command.params); expect(results.didCreateFile).toBeTruthy(); - expect(results.uri.path.endsWith('hello-world.md')).toBeTruthy(); + expect(results.uri.path).toMatch(/hello-world.md$/); const newNoteDoc = window.activeTextEditor.document; expect(newNoteDoc.uri.path).toMatch(/hello-world.md$/); diff --git a/packages/foam-vscode/src/features/commands/create-note.ts b/packages/foam-vscode/src/features/commands/create-note.ts index 4f48807d8..1c7c6615b 100644 --- a/packages/foam-vscode/src/features/commands/create-note.ts +++ b/packages/foam-vscode/src/features/commands/create-note.ts @@ -1,11 +1,14 @@ -import * as vscode from 'vscode'; +import { workspace, commands, WorkspaceEdit, ExtensionContext } from 'vscode'; import { URI } from '../../core/model/uri'; import { askUserForTemplate, getDefaultTemplateUri, - getPathFromTitle, NoteFactory, } from '../../services/templates'; +import { NoteCreationEngine } from '../../services/note-creation-engine'; +import { TriggerFactory } from '../../services/note-creation-triggers'; +import { TemplateLoader } from '../../services/template-loader'; +import { Template } from '../../services/note-creation-types'; import { Resolver } from '../../services/variable-resolver'; import { asAbsoluteWorkspaceUri, fileExists } from '../../services/editor'; import { isSome } from '../../core/utils'; @@ -14,15 +17,19 @@ import { Foam } from '../../core/model/foam'; import { Location } from '../../core/model/location'; import { MarkdownLink } from '../../core/services/markdown-link'; import { ResourceLink } from '../../core/model/note'; -import { toVsCodeRange, toVsCodeUri } from '../../utils/vsc-utils'; +import { + fromVsCodeUri, + toVsCodeRange, + toVsCodeUri, +} from '../../utils/vsc-utils'; export default async function activate( - context: vscode.ExtensionContext, + context: ExtensionContext, foamPromise: Promise ) { const foam = await foamPromise; context.subscriptions.push( - vscode.commands.registerCommand(CREATE_NOTE_COMMAND.command, args => + commands.registerCommand(CREATE_NOTE_COMMAND.command, args => createNote(args, foam) ) ); @@ -33,11 +40,11 @@ interface CreateNoteArgs { * The path of the note to create. * If relative it will be resolved against the workspace root. */ - notePath?: string; + notePath?: string | URI; /** * The path of the template to use. */ - templatePath?: string; + templatePath?: string | URI; /** * Whether to ask the user to select a template for the new note. If so, overwrites templatePath. */ @@ -54,7 +61,7 @@ interface CreateNoteArgs { /** * The date used to resolve the FOAM_DATE_* variables. in YYYY-MM-DD format */ - date?: string; + date?: string | Date; /** * The title of the note (translates into the FOAM_TITLE variable) */ @@ -84,22 +91,23 @@ const DEFAULT_NEW_NOTE_TEXT = `# \${FOAM_TITLE} export async function createNote(args: CreateNoteArgs, foam: Foam) { args = args ?? {}; - const date = isSome(args.date) ? new Date(Date.parse(args.date)) : new Date(); - const resolver = new Resolver( - new Map(Object.entries(args.variables ?? {})), - date - ); - if (args.title) { - resolver.define('FOAM_TITLE', args.title); - } - const text = args.text ?? DEFAULT_NEW_NOTE_TEXT; - const schemaSource = vscode.workspace.workspaceFolders[0].uri; - const noteUri = - args.notePath && - new URI({ - scheme: schemaSource.scheme, - path: args.notePath, - }); + const date = + typeof args.date === 'string' + ? new Date(Date.parse(args.date)) + : args.date instanceof Date + ? args.date + : new Date(); + + // Create appropriate trigger based on context + const trigger = args.sourceLink + ? TriggerFactory.createPlaceholderTrigger( + args.sourceLink.uri, + foam.workspace.find(new URI(args.sourceLink.uri))?.title || 'Unknown', + args.sourceLink + ) + : TriggerFactory.createCommandTrigger('foam-vscode.create-note'); + + // Determine template path let templateUri: URI; if (args.askForTemplate) { const selectedTemplate = await askUserForTemplate(); @@ -111,41 +119,84 @@ export async function createNote(args: CreateNoteArgs, foam: Foam) { } else { templateUri = args.templatePath ? asAbsoluteWorkspaceUri(args.templatePath) - : getDefaultTemplateUri(); + : await getDefaultTemplateUri(); } - const createdNote = (await fileExists(templateUri)) - ? await NoteFactory.createFromTemplate( - templateUri, - resolver, - noteUri, - text, - args.onFileExists - ) - : await NoteFactory.createNote( - noteUri ?? (await getPathFromTitle(templateUri.scheme, resolver)), - text, - resolver, - args.onFileExists, - args.onRelativeNotePath - ); + // Load template using the new system + const templateLoader = new TemplateLoader(); + let template: Template; + + try { + if (!templateUri) { + template = { + type: 'markdown', + content: args.text || DEFAULT_NEW_NOTE_TEXT, + }; + } else if (await fileExists(templateUri)) { + template = await templateLoader.loadTemplate(templateUri); + } else { + throw new Error(`Template file not found: ${templateUri}`); + } + } catch (error) { + throw new Error( + `Failed to load template (${templateUri}): ${error.message}` + ); + } + + // If notePath is provided, add it to template metadata to avoid unnecessary title resolution + if (args.notePath && template.type === 'markdown') { + template.metadata = template.metadata || new Map(); + template.metadata.set( + 'filepath', + args.notePath instanceof URI ? args.notePath.toFsPath() : args.notePath + ); + } - if (args.sourceLink) { + // Create resolver with all variables upfront + const resolver = new Resolver( + new Map(Object.entries(args.variables ?? {})), + date + ); + + // Define all variables in the resolver with proper mapping + if (args.title) { + resolver.define('FOAM_TITLE', args.title); + } + + // Process template using the new engine with unified resolver + const engine = new NoteCreationEngine( + foam, + workspace.workspaceFolders.map(folder => fromVsCodeUri(folder.uri)) + ); + const result = await engine.processTemplate(trigger, template, resolver); + + // Create the note using NoteFactory with the same resolver + const createdNote = await NoteFactory.createNote( + result.filepath, + result.content, + resolver, + args.onFileExists, + args.onRelativeNotePath + ); + + // Handle source link updates for placeholders + if (args.sourceLink && createdNote.uri) { const identifier = foam.workspace.getIdentifier(createdNote.uri); const edit = MarkdownLink.createUpdateLinkEdit(args.sourceLink.data, { target: identifier, }); if (edit.newText !== args.sourceLink.data.rawText) { - const updateLink = new vscode.WorkspaceEdit(); + const updateLink = new WorkspaceEdit(); const uri = toVsCodeUri(args.sourceLink.uri); updateLink.replace( uri, toVsCodeRange(args.sourceLink.range), edit.newText ); - await vscode.workspace.applyEdit(updateLink); + await workspace.applyEdit(updateLink); } } + return createdNote; } diff --git a/packages/foam-vscode/src/features/commands/open-daily-note-for-date.spec.ts b/packages/foam-vscode/src/features/commands/open-daily-note-for-date.spec.ts index ae0468ca4..a242410a9 100644 --- a/packages/foam-vscode/src/features/commands/open-daily-note-for-date.spec.ts +++ b/packages/foam-vscode/src/features/commands/open-daily-note-for-date.spec.ts @@ -1,8 +1,9 @@ +/* @unit-ready */ import dateFormat from 'dateformat'; import { commands, window } from 'vscode'; describe('open-daily-note-for-date command', () => { - it('offers to pick which template to use', async () => { + it('offers to pick which date to use', async () => { const spy = jest .spyOn(window, 'showQuickPick') .mockImplementationOnce(jest.fn(() => Promise.resolve(undefined))); diff --git a/packages/foam-vscode/src/features/commands/open-daily-note-for-date.ts b/packages/foam-vscode/src/features/commands/open-daily-note-for-date.ts index 0fc07062a..548dae85e 100644 --- a/packages/foam-vscode/src/features/commands/open-daily-note-for-date.ts +++ b/packages/foam-vscode/src/features/commands/open-daily-note-for-date.ts @@ -23,7 +23,7 @@ export default async function activate( .then(item => { return item?.date; }); - return openDailyNoteFor(date); + return openDailyNoteFor(date, await foamPromise); } ) ); diff --git a/packages/foam-vscode/src/features/commands/open-daily-note.ts b/packages/foam-vscode/src/features/commands/open-daily-note.ts index 5066ee462..73051451f 100644 --- a/packages/foam-vscode/src/features/commands/open-daily-note.ts +++ b/packages/foam-vscode/src/features/commands/open-daily-note.ts @@ -1,11 +1,15 @@ import { ExtensionContext, commands } from 'vscode'; import { getFoamVsCodeConfig } from '../../services/config'; import { openDailyNoteFor } from '../../dated-notes'; +import { Foam } from '../../core/model/foam'; -export default async function activate(context: ExtensionContext) { +export default async function activate( + context: ExtensionContext, + foamPromise: Promise +) { context.subscriptions.push( - commands.registerCommand('foam-vscode.open-daily-note', () => - openDailyNoteFor(new Date()) + commands.registerCommand('foam-vscode.open-daily-note', async () => + openDailyNoteFor(new Date(), await foamPromise) ) ); diff --git a/packages/foam-vscode/src/features/commands/open-dated-note.ts b/packages/foam-vscode/src/features/commands/open-dated-note.ts index 99600d641..dbe44c157 100644 --- a/packages/foam-vscode/src/features/commands/open-dated-note.ts +++ b/packages/foam-vscode/src/features/commands/open-dated-note.ts @@ -1,18 +1,23 @@ import { ExtensionContext, commands } from 'vscode'; +import { Foam } from '../../core/model/foam'; import { getFoamVsCodeConfig } from '../../services/config'; import { createDailyNoteIfNotExists, openDailyNoteFor, } from '../../dated-notes'; -export default async function activate(context: ExtensionContext) { +export default async function activate( + context: ExtensionContext, + foamPromise: Promise +) { context.subscriptions.push( - commands.registerCommand('foam-vscode.open-dated-note', date => { + commands.registerCommand('foam-vscode.open-dated-note', async date => { + const foam = await foamPromise; switch (getFoamVsCodeConfig('dateSnippets.afterCompletion')) { case 'navigateToNote': - return openDailyNoteFor(date); + return openDailyNoteFor(date, foam); case 'createNote': - return createDailyNoteIfNotExists(date); + return createDailyNoteIfNotExists(date, foam); } }) ); diff --git a/packages/foam-vscode/src/features/commands/open-resource.spec.ts b/packages/foam-vscode/src/features/commands/open-resource.spec.ts index 9d7938b2e..f61366a1f 100644 --- a/packages/foam-vscode/src/features/commands/open-resource.spec.ts +++ b/packages/foam-vscode/src/features/commands/open-resource.spec.ts @@ -3,19 +3,28 @@ import { CommandDescriptor } from '../../utils/commands'; import { OpenResourceArgs, OPEN_COMMAND } from './open-resource'; import * as filter from '../../core/services/resource-filter'; import { URI } from '../../core/model/uri'; -import { closeEditors, createFile } from '../../test/test-utils-vscode'; +import { + closeEditors, + createFile, + waitForNoteInFoamWorkspace, +} from '../../test/test-utils-vscode'; import { deleteFile } from '../../services/editor'; import waitForExpect from 'wait-for-expect'; describe('open-resource command', () => { beforeEach(async () => { - await jest.resetAllMocks(); + jest.resetAllMocks(); + await closeEditors(); + }); + + afterEach(async () => { await closeEditors(); }); it('URI param has precedence over filter', async () => { const spy = jest.spyOn(filter, 'createFilter'); const noteA = await createFile('Note A for open command'); + await waitForNoteInFoamWorkspace(noteA.uri); const command: CommandDescriptor = { name: OPEN_COMMAND.command, @@ -26,7 +35,8 @@ describe('open-resource command', () => { }; await commands.executeCommand(command.name, command.params); - waitForExpect(() => { + await waitForExpect(() => { + expect(window.activeTextEditor).toBeTruthy(); expect(window.activeTextEditor.document.uri.path).toEqual(noteA.uri.path); }); expect(spy).not.toHaveBeenCalled(); @@ -36,15 +46,17 @@ describe('open-resource command', () => { it('URI param accept URI object, or path', async () => { const noteA = await createFile('Note A for open command'); + await waitForNoteInFoamWorkspace(noteA.uri); const uriCommand: CommandDescriptor = { name: OPEN_COMMAND.command, params: { - uri: URI.file('path/to/file.md'), + uri: noteA.uri, }, }; await commands.executeCommand(uriCommand.name, uriCommand.params); - waitForExpect(() => { + await waitForExpect(() => { + expect(window.activeTextEditor).toBeTruthy(); expect(window.activeTextEditor.document.uri.path).toEqual(noteA.uri.path); }); @@ -53,17 +65,18 @@ describe('open-resource command', () => { const pathCommand: CommandDescriptor = { name: OPEN_COMMAND.command, params: { - uri: URI.file('path/to/file.md'), + uri: noteA.uri.path, }, }; await commands.executeCommand(pathCommand.name, pathCommand.params); - waitForExpect(() => { + await waitForExpect(() => { + expect(window.activeTextEditor).toBeTruthy(); expect(window.activeTextEditor.document.uri.path).toEqual(noteA.uri.path); }); await deleteFile(noteA.uri); }); - it('User is notified if no resource is found', async () => { + it('User is notified if no resource is found with filter', async () => { const spy = jest.spyOn(window, 'showInformationMessage'); const command: CommandDescriptor = { @@ -74,12 +87,33 @@ describe('open-resource command', () => { }; await commands.executeCommand(command.name, command.params); - waitForExpect(() => { + await waitForExpect(() => { + expect(spy).toHaveBeenCalled(); + }); + }); + + it('User is notified if no resource is found with URI', async () => { + const spy = jest.spyOn(window, 'showInformationMessage'); + + const command: CommandDescriptor = { + name: OPEN_COMMAND.command, + params: { + uri: URI.file('path/to/nonexistent.md'), + }, + }; + await commands.executeCommand(command.name, command.params); + + await waitForExpect(() => { expect(spy).toHaveBeenCalled(); }); }); it('filter with multiple results will show a quick pick', async () => { + const noteA = await createFile('Note A for filter test'); + const noteB = await createFile('Note B for filter test'); + await waitForNoteInFoamWorkspace(noteA.uri); + await waitForNoteInFoamWorkspace(noteB.uri); + const spy = jest .spyOn(window, 'showQuickPick') .mockImplementationOnce(jest.fn(() => Promise.resolve(undefined))); @@ -92,8 +126,11 @@ describe('open-resource command', () => { }; await commands.executeCommand(command.name, command.params); - waitForExpect(() => { + await waitForExpect(() => { expect(spy).toHaveBeenCalled(); }); + + await deleteFile(noteA.uri); + await deleteFile(noteB.uri); }); }); diff --git a/packages/foam-vscode/src/features/commands/open-resource.ts b/packages/foam-vscode/src/features/commands/open-resource.ts index 1385e6daf..5b4cba642 100644 --- a/packages/foam-vscode/src/features/commands/open-resource.ts +++ b/packages/foam-vscode/src/features/commands/open-resource.ts @@ -82,13 +82,18 @@ async function openResource(workspace: FoamWorkspace, args?: OpenResourceArgs) { ); } - if (isSome(item)) { - const targetUri = - item.uri.path === vscode.window.activeTextEditor?.document.uri.path - ? vscode.window.activeTextEditor?.document.uri - : toVsCodeUri(item.uri.asPlain()); - return vscode.commands.executeCommand('vscode.open', targetUri); + if (isNone(item)) { + vscode.window.showInformationMessage( + 'Foam: No note matches given filters or URI.' + ); + return; } + + const targetUri = + item.uri.path === vscode.window.activeTextEditor?.document.uri.path + ? vscode.window.activeTextEditor?.document.uri + : toVsCodeUri(item.uri.asPlain()); + return vscode.commands.executeCommand('vscode.open', targetUri); } interface ResourceItem extends vscode.QuickPickItem { diff --git a/packages/foam-vscode/src/features/hover-provider.spec.ts b/packages/foam-vscode/src/features/hover-provider.spec.ts index b2f65a94d..2a0ea1e38 100644 --- a/packages/foam-vscode/src/features/hover-provider.spec.ts +++ b/packages/foam-vscode/src/features/hover-provider.spec.ts @@ -3,15 +3,16 @@ import { createMarkdownParser } from '../core/services/markdown-parser'; import { MarkdownResourceProvider } from '../core/services/markdown-provider'; import { FoamGraph } from '../core/model/graph'; import { FoamWorkspace } from '../core/model/workspace'; +import { URI } from '../core/model/uri'; import { cleanWorkspace, closeEditors, createFile, showInEditor, } from '../test/test-utils-vscode'; +import { readFileFromFs, TEST_DATA_DIR } from '../test/test-utils'; import { toVsCodeUri } from '../utils/vsc-utils'; import { HoverProvider } from './hover-provider'; -import { readFileFromFs } from '../test/test-utils'; import { FileDataStore } from '../test/test-datastore'; // We can't use createTestWorkspace from /packages/foam-vscode/src/test/test-utils.ts @@ -36,7 +37,7 @@ describe('Hover provider', () => { isCancellationRequested: false, onCancellationRequested: null, }; - const parser = createMarkdownParser([]); + const parser = createMarkdownParser(); const hoverEnabled = () => true; beforeAll(async () => { @@ -91,7 +92,9 @@ describe('Hover provider', () => { `this is a link to [[${fileB.name}]] end of the line.` ); const noteA = parser.parse(fileA.uri, fileA.content); + (noteA as any).rawText = fileA.content; const noteB = parser.parse(fileB.uri, fileB.content); + (noteB as any).rawText = fileB.content; const ws = createWorkspace().set(noteA).set(noteB); const graph = FoamGraph.fromWorkspace(ws); @@ -110,6 +113,7 @@ describe('Hover provider', () => { `this is a link to [[a placeholder]] end of the line.` ); const noteA = parser.parse(fileA.uri, fileA.content); + (noteA as any).rawText = fileA.content; const ws = createWorkspace().set(noteA); const graph = FoamGraph.fromWorkspace(ws); @@ -315,6 +319,9 @@ The content of file B`); .set(parser.parse(fileA.uri, fileA.content)) .set(parser.parse(fileB.uri, fileB.content)) .set(parser.parse(fileC.uri, fileC.content)); + (fileA as any).rawText = fileA.content; + (fileB as any).rawText = fileB.content; + (fileC as any).rawText = fileC.content; const graph = FoamGraph.fromWorkspace(ws); const { doc } = await showInEditor(fileB.uri); @@ -335,4 +342,104 @@ The content of file B`); graph.dispose(); }); }); + + describe('with block identifiers', () => { + it('should return hover content for a wikilink to a block', async () => { + const fileWithBlockId = await createFile( + '# Note with block id\n\nThis is a paragraph. ^block-1' + ); + const linkContent = `[[${fileWithBlockId.name}#^block-1]]`; + const fileLinkingToBlockId = await createFile( + `# Note linking to block id\n\nThis note links to ${linkContent}.` + ); + + const noteWithBlockId = parser.parse( + fileWithBlockId.uri, + fileWithBlockId.content + ); + const noteLinkingToBlockId = parser.parse( + fileLinkingToBlockId.uri, + fileLinkingToBlockId.content + ); + + const ws = createWorkspace() + .set(noteWithBlockId) + .set(noteLinkingToBlockId); + const graph = FoamGraph.fromWorkspace(ws); + + const provider = new HoverProvider(hoverEnabled, ws, graph, parser); + const { doc } = await showInEditor(noteLinkingToBlockId.uri); + const linkPosition = fileLinkingToBlockId.content.indexOf(linkContent); + const pos = doc.positionAt(linkPosition + 2); + + const result = await provider.provideHover(doc, pos, noCancelToken); + + expect(result.contents).toHaveLength(3); + expect(getValue(result.contents[0])).toEqual( + 'This is a paragraph. ^block-1' + ); + ws.dispose(); + graph.dispose(); + }); + }); +}); + +describe('Mixed Scenario Hover', () => { + const noCancelToken: vscode.CancellationToken = { + isCancellationRequested: false, + onCancellationRequested: null, + }; + it('should provide correct hover information for all link types', async () => { + const parser = createMarkdownParser([]); + const ws = createWorkspace(); + + const mixedTargetFile = await createFile( + await readFileFromFs( + TEST_DATA_DIR.joinPath('block-identifiers', 'mixed-target.md') + ), + ['mixed-target.md'] + ); + const mixedOtherFile = await createFile( + await readFileFromFs( + TEST_DATA_DIR.joinPath('block-identifiers', 'mixed-other.md') + ), + ['mixed-other.md'] + ); + const mixedSourceFile = await createFile( + await readFileFromFs( + TEST_DATA_DIR.joinPath('block-identifiers', 'mixed-source.md') + ), + ['mixed-source.md'] + ); + + const mixedTarget = parser.parse( + mixedTargetFile.uri, + mixedTargetFile.content + ); + (mixedTarget as any).rawText = mixedTargetFile.content; + const mixedOther = parser.parse(mixedOtherFile.uri, mixedOtherFile.content); + (mixedOther as any).rawText = mixedOtherFile.content; + const mixedSource = parser.parse( + mixedSourceFile.uri, + mixedSourceFile.content + ); + (mixedSource as any).rawText = mixedSourceFile.content; + + ws.set(mixedTarget).set(mixedOther).set(mixedSource); + const graph = FoamGraph.fromWorkspace(ws); + const provider = new HoverProvider(() => true, ws, graph, parser); + const { doc } = await showInEditor(mixedSource.uri); + + // Test hover on paragraph block link + let pos = new vscode.Position(4, 30); + let result = await provider.provideHover(doc, pos, noCancelToken); + expect(getValue(result.contents[0])).toContain( + 'Here is a paragraph with a block identifier. ^para-block' + ); + + // Test hover on list item block link + pos = new vscode.Position(5, 30); + result = await provider.provideHover(doc, pos, noCancelToken); + expect(getValue(result.contents[0])).toContain('- List item 2 ^list-block'); + }); }); diff --git a/packages/foam-vscode/src/features/hover-provider.ts b/packages/foam-vscode/src/features/hover-provider.ts index 0d8874547..47687e3f8 100644 --- a/packages/foam-vscode/src/features/hover-provider.ts +++ b/packages/foam-vscode/src/features/hover-provider.ts @@ -5,7 +5,12 @@ import { ConfigurationMonitor, monitorFoamVsCodeConfig, } from '../services/config'; -import { ResourceLink, ResourceParser } from '../core/model/note'; +import { + ResourceLink, + ResourceParser, + Resource, + Section, +} from '../core/model/note'; import { Foam } from '../core/model/foam'; import { FoamWorkspace } from '../core/model/workspace'; import { Range } from '../core/model/range'; @@ -16,6 +21,30 @@ import { commandAsURI } from '../utils/commands'; import { Location } from '../core/model/location'; import { getNoteTooltip, getFoamDocSelectors } from '../services/editor'; import { isSome } from '../core/utils'; +import { MarkdownLink } from '../core/services/markdown-link'; + +/** + * Extracts a range of content from a multi-line string. + * This is used to display the content of a specific section (e.g., a heading and its content) + * in the hover preview, rather than the entire note. + * @param content The full string content of the note. + * @param range The range to extract. + * @returns The substring corresponding to the given range. + */ +const sliceContent = (content: string, range: Range): string => { + const lines = content.split('\n'); + const { start, end } = range; + + if (start.line === end.line) { + return lines[start.line]?.substring(start.character, end.character) ?? ''; + } + + const firstLine = lines[start.line]?.substring(start.character) ?? ''; + const lastLine = lines[end.line]?.substring(0, end.character) ?? ''; + const middleLines = lines.slice(start.line + 1, end.line); + + return [firstLine, ...middleLines, lastLine].join('\n'); +}; export const CONFIG_KEY = 'links.hover.enable'; @@ -77,10 +106,26 @@ export class HoverProvider implements vscode.HoverProvider { const documentUri = fromVsCodeUri(document.uri); const targetUri = this.workspace.resolveLink(startResource, targetLink); - const sources = uniqWith( - this.graph + + // --- Start of Block ID Feature Changes --- + + // Extract the fragment (e.g., #my-header or #^my-block-id) from the link. + // This is crucial for handling links to specific sections or blocks within a note. + const { section: linkFragment } = MarkdownLink.analyzeLink(targetLink); + + let backlinks: import('../core/model/graph').Connection[]; + + // If a fragment exists, we need to be more precise with backlink gathering. + if (linkFragment) { + backlinks = this.graph .getBacklinks(targetUri) - .filter(link => !link.source.isEqual(documentUri)) + .filter(conn => conn.target.isEqual(targetUri)); + } else { + backlinks = this.graph.getBacklinks(targetUri); + } + const sources = uniqWith( + backlinks + .filter(link => link.source.toFsPath() !== documentUri.toFsPath()) .map(link => link.source), (u1, u2) => u1.isEqual(u2) ); @@ -101,11 +146,44 @@ export class HoverProvider implements vscode.HoverProvider { let mdContent = null; if (!targetUri.isPlaceholder()) { - const content: string = await this.workspace.readAsMarkdown(targetUri); + // Use the in-memory workspace resource for section/block lookup (not a fresh parse from disk) + const targetFileUri = targetUri.with({ fragment: '' }); + const targetResource = this.workspace.get(targetFileUri); + let content: string | null = null; + + if (linkFragment) { + // Use the in-memory resource for section/block lookup + const section: Section | undefined = Resource.findSection( + targetResource, + linkFragment + ); + if (isSome(section)) { + if (section.type === 'block') { + // For block IDs, show the block label (e.g., the list item or paragraph) + content = section.label; + } else if (section.type === 'heading') { + // For headings, show the content under the heading (sliceContent) + const noteText = await this.workspace.readAsMarkdown(targetFileUri); + content = sliceContent(noteText, section.range); + } else { + // Fallback: show the section label + content = (section as any).label; + } + } else { + // Fallback: show the whole note content (from workspace, robust to test/production) + content = await this.workspace.readAsMarkdown(targetFileUri); + } + } else { + // If there is no fragment, show the entire note content, minus frontmatter. + content = await this.workspace.readAsMarkdown(targetFileUri); + } - mdContent = isSome(content) - ? getNoteTooltip(content) - : this.workspace.get(targetUri).title; + if (isSome(content)) { + content = content.replace(/---[\s\S]*?---/, '').trim(); + mdContent = getNoteTooltip(content); + } else { + mdContent = targetResource.title; + } } const command = CREATE_NOTE_COMMAND.forPlaceholder( diff --git a/packages/foam-vscode/src/features/link-completion.spec.ts b/packages/foam-vscode/src/features/link-completion.spec.ts index 8447ef814..c07f85c1d 100644 --- a/packages/foam-vscode/src/features/link-completion.spec.ts +++ b/packages/foam-vscode/src/features/link-completion.spec.ts @@ -23,7 +23,10 @@ describe('Link Completion', () => { createTestNote({ root, uri: 'file-name.md', - sections: ['Section One', 'Section Two'], + sections: [ + { label: 'Section One', level: 1 }, + { label: 'Section Two', level: 1 }, + ], }) ) .set( @@ -159,7 +162,7 @@ describe('Link Completion', () => { ); expect(links.items.map(i => i.label)).toEqual([ - workspace.getIdentifier(noteUri), + ws.getIdentifier(noteUri), ]); } ); @@ -187,7 +190,7 @@ describe('Link Completion', () => { ); expect(links.items.map(i => i.insertText)).toEqual([ - workspace.getIdentifier(noteUri), + ws.getIdentifier(noteUri), ]); } ); @@ -202,7 +205,7 @@ describe('Link Completion', () => { ); expect(links.items.map(i => i.insertText)).toEqual([ - `${workspace.getIdentifier(noteUri)}|My Note Title`, + `${ws.getIdentifier(noteUri)}|My Note Title`, ]); } ); @@ -281,4 +284,35 @@ alias: alias-a expect(aliasCompletionItem.label).toBe('alias-a'); expect(aliasCompletionItem.insertText).toBe('new-note-with-alias|alias-a'); }); + + it('should return block identifiers for the given note', async () => { + const noteWithBlocks = await createFile( + ` +# Note with blocks + +This is a paragraph. ^p1 + +- list item 1 ^li1 +- list item 2 + +### A heading ^h1 +`, + ['note-with-blocks.md'] + ); + ws.set(parser.parse(noteWithBlocks.uri, noteWithBlocks.content)); + + const text = '[[note-with-blocks#^'; + const { uri } = await createFile(text); + const { doc } = await showInEditor(uri); + const provider = new SectionCompletionProvider(ws); + + const links = await provider.provideCompletionItems( + doc, + new vscode.Position(0, text.length) + ); + + expect(new Set(links.items.map(i => i.label))).toEqual( + new Set(['Note with blocks', 'A heading', '^p1', '^li1', '^h1']) + ); + }); }); diff --git a/packages/foam-vscode/src/features/link-completion.ts b/packages/foam-vscode/src/features/link-completion.ts index f0dda23cf..bbea41263 100644 --- a/packages/foam-vscode/src/features/link-completion.ts +++ b/packages/foam-vscode/src/features/link-completion.ts @@ -20,6 +20,11 @@ const COMPLETION_CURSOR_MOVE = { export const WIKILINK_REGEX = /\[\[[^[\]]*(?!.*\]\])/; export const SECTION_REGEX = /\[\[([^[\]]*#(?!.*\]\]))/; +/** + * Activates the completion features for Foam. + * This includes registering completion providers for wikilinks and sections, + * and a command to handle cursor movement after completion. + */ export default async function activate( context: vscode.ExtensionContext, foamPromise: Promise @@ -87,6 +92,10 @@ export default async function activate( ); } +/** + * Provides completion items for sections (headings and block IDs) within a note. + * Triggered when the user types `#` inside a wikilink. + */ export class SectionCompletionProvider implements vscode.CompletionItemProvider { @@ -108,6 +117,8 @@ export class SectionCompletionProvider return null; } + // Determine the target resource. If the link is just `[[#...]]`, + // it refers to the current document. Otherwise, it's the text before the '#'. const resourceId = match[1] === '#' ? fromVsCodeUri(document.uri) : match[1].slice(0, -1); @@ -119,17 +130,68 @@ export class SectionCompletionProvider position.character ); if (resource) { - const items = resource.sections.map(b => { - const item = new ResourceCompletionItem( - b.label, - vscode.CompletionItemKind.Text, - resource.uri.with({ fragment: b.label }) - ); - item.sortText = String(b.range.start.line).padStart(5, '0'); - item.range = replacementRange; - item.commitCharacters = sectionCommitCharacters; - item.command = COMPLETION_CURSOR_MOVE; - return item; + const items = resource.sections.flatMap(section => { + const sectionItems: vscode.CompletionItem[] = []; + switch (section.type) { + case 'heading': + // For headings, we provide a completion item for the slugified heading ID. + if (section.id) { + const slugItem = new ResourceCompletionItem( + section.label, + vscode.CompletionItemKind.Text, + resource.uri.with({ fragment: section.id }) + ); + slugItem.sortText = String(section.range.start.line).padStart( + 5, + '0' + ); + slugItem.range = replacementRange; + slugItem.commitCharacters = sectionCommitCharacters; + slugItem.command = COMPLETION_CURSOR_MOVE; + slugItem.insertText = section.id; + sectionItems.push(slugItem); + } + // If a heading also has a block ID, we provide a separate completion for it. + // The label includes the `^` for clarity, but the inserted text does not. + if (section.blockId) { + const blockIdItem = new ResourceCompletionItem( + section.blockId, + vscode.CompletionItemKind.Text, + resource.uri.with({ fragment: section.blockId.substring(1) }) + ); + blockIdItem.sortText = String(section.range.start.line).padStart( + 5, + '0' + ); + blockIdItem.range = replacementRange; + blockIdItem.commitCharacters = sectionCommitCharacters; + blockIdItem.command = COMPLETION_CURSOR_MOVE; + blockIdItem.insertText = section.blockId.substring(1); + sectionItems.push(blockIdItem); + } + break; + case 'block': { + // For non-heading elements (paragraphs, list items, etc.), we only offer + // completion if they have an explicit block ID. + const blockIdItem = new ResourceCompletionItem( + section.blockId, // e.g. ^my-block-id + vscode.CompletionItemKind.Text, + resource.uri.with({ fragment: section.blockId.substring(1) }) // fragment is 'my-block-id' + ); + blockIdItem.sortText = String(section.range.start.line).padStart( + 5, + '0' + ); + blockIdItem.range = replacementRange; + blockIdItem.commitCharacters = sectionCommitCharacters; + blockIdItem.command = COMPLETION_CURSOR_MOVE; + // Insert the block ID without the leading `^`. + blockIdItem.insertText = section.blockId.substring(1); + sectionItems.push(blockIdItem); + break; + } + } + return sectionItems; }); return new vscode.CompletionList(items); } @@ -148,6 +210,10 @@ export class SectionCompletionProvider } } +/** + * Provides completion items for wikilinks. + * Triggered when the user types `[[`. + */ export class WikilinkCompletionProvider implements vscode.CompletionItemProvider { @@ -268,7 +334,8 @@ export class WikilinkCompletionProvider } /** - * A CompletionItem related to a Resource + * A custom CompletionItem that includes the URI of the resource it refers to. + * This is used to resolve additional information, like tooltips, on demand. */ class ResourceCompletionItem extends vscode.CompletionItem { constructor( diff --git a/packages/foam-vscode/src/features/navigation-provider.spec.ts b/packages/foam-vscode/src/features/navigation-provider.spec.ts index 407434b68..5f361cc6b 100644 --- a/packages/foam-vscode/src/features/navigation-provider.spec.ts +++ b/packages/foam-vscode/src/features/navigation-provider.spec.ts @@ -182,6 +182,33 @@ describe('Document navigation', () => { expect(definitions[0].targetUri).toEqual(toVsCodeUri(fileA.uri)); }); + it('should create a definition for a wikilink to a block', async () => { + const fileA = await createFile( + '# File A\n\nThis is a paragraph. ^block-id', + ['file-a.md'] + ); + const fileB = await createFile(`this is a link to [[file-a#^block-id]].`); + + const ws = createTestWorkspace() + .set(parser.parse(fileA.uri, fileA.content)) + .set(parser.parse(fileB.uri, fileB.content)); + const graph = FoamGraph.fromWorkspace(ws); + + const { doc } = await showInEditor(fileB.uri); + const provider = new NavigationProvider(ws, graph, parser); + const definitions = await provider.provideDefinition( + doc, + new vscode.Position(0, 22) + ); + + expect(definitions.length).toEqual(1); + expect(definitions[0].targetUri).toEqual(toVsCodeUri(fileA.uri)); + expect(definitions[0].targetRange).toEqual(new vscode.Range(2, 0, 2, 30)); + expect(definitions[0].targetSelectionRange).toEqual( + new vscode.Range(2, 0, 2, 30) + ); + }); + it('should support wikilink aliases in tables using escape character', async () => { const fileA = await createFile('# File that has to be aliased'); const fileB = await createFile(` diff --git a/packages/foam-vscode/src/features/navigation-provider.ts b/packages/foam-vscode/src/features/navigation-provider.ts index b6c1d1176..e5c707324 100644 --- a/packages/foam-vscode/src/features/navigation-provider.ts +++ b/packages/foam-vscode/src/features/navigation-provider.ts @@ -122,7 +122,7 @@ export class NavigationProvider ? section.range : Range.createFromPosition(Position.create(0, 0), Position.create(0, 0)); const targetSelectionRange = section - ? section.range + ? (section as any).labelRange || section.range // Use labelRange for headings, fallback to full section range : Range.createFromPosition(targetRange.start); const result: vscode.LocationLink = { diff --git a/packages/foam-vscode/src/features/panels/connections.spec.ts b/packages/foam-vscode/src/features/panels/connections.spec.ts index f6c843b6d..304c814f3 100644 --- a/packages/foam-vscode/src/features/panels/connections.spec.ts +++ b/packages/foam-vscode/src/features/panels/connections.spec.ts @@ -1,5 +1,10 @@ +/* @unit-ready */ import { workspace, window } from 'vscode'; -import { createTestNote, createTestWorkspace } from '../../test/test-utils'; +import { + createTestNote, + createTestWorkspace, + TEST_DATA_DIR, +} from '../../test/test-utils'; import { cleanWorkspace, closeEditors, @@ -13,6 +18,9 @@ import { ResourceRangeTreeItem, ResourceTreeItem, } from './utils/tree-view-utils'; +import { FoamWorkspace } from '../../core/model/workspace'; +import { Resource } from '../../core/model/note'; +import { createMarkdownParser } from '../../core/services/markdown-parser'; describe('Backlinks panel', () => { beforeAll(async () => { @@ -158,3 +166,84 @@ describe('Backlinks panel', () => { ); }); }); + +describe('Backlinks panel with block identifiers', () => { + let ws: FoamWorkspace; + let graph: FoamGraph; + let provider: ConnectionsTreeDataProvider; + let noteWithBlockId: Resource; + let noteLinkingToBlockId: Resource; + + beforeAll(async () => { + await cleanWorkspace(); + + const noteWithBlockIdUri = TEST_DATA_DIR.joinPath( + 'block-identifiers', + 'note-with-block-id.md' + ); + const noteLinkingToBlockIdUri = TEST_DATA_DIR.joinPath( + 'block-identifiers', + 'note-linking-to-block-id.md' + ); + + const noteWithBlockIdContent = Buffer.from( + await workspace.fs.readFile(toVsCodeUri(noteWithBlockIdUri)) + ).toString('utf8'); + const noteLinkingToBlockIdContent = Buffer.from( + await workspace.fs.readFile(toVsCodeUri(noteLinkingToBlockIdUri)) + ).toString('utf8'); + + const parser = createMarkdownParser(); + const rootUri = getUriInWorkspace('just-a-ref.md').getDirectory(); + + noteWithBlockId = parser.parse( + rootUri.joinPath('note-with-block-id.md'), + noteWithBlockIdContent + ); + noteLinkingToBlockId = parser.parse( + rootUri.joinPath('note-linking-to-block-id.md'), + noteLinkingToBlockIdContent + ); + + await createNote(noteWithBlockId); + await createNote(noteLinkingToBlockId); + + ws = createTestWorkspace(); + ws.set(noteWithBlockId); + ws.set(noteLinkingToBlockId); + graph = FoamGraph.fromWorkspace(ws, true); + provider = new ConnectionsTreeDataProvider( + ws, + graph, + new MapBasedMemento(), + false + ); + }); + + afterAll(async () => { + if (graph) graph.dispose(); + if (ws) ws.dispose(); + if (provider) provider.dispose(); + await cleanWorkspace(); + }); + + beforeEach(async () => { + await closeEditors(); + provider.target = undefined; + }); + + it('shows backlinks to blocks', async () => { + provider.target = noteWithBlockId.uri; + await provider.refresh(); + const notes = (await provider.getChildren()) as ResourceTreeItem[]; + expect(notes.map(n => n.resource.uri.path)).toEqual([ + noteLinkingToBlockId.uri.path, + ]); + const links = (await provider.getChildren( + notes[0] + )) as ResourceRangeTreeItem[]; + expect(links[0].label).toEqual( + 'This is a paragraph with a block identifier. ^block-1' + ); + }); +}); diff --git a/packages/foam-vscode/src/features/panels/placeholders.ts b/packages/foam-vscode/src/features/panels/placeholders.ts index da52256ab..e802018c6 100644 --- a/packages/foam-vscode/src/features/panels/placeholders.ts +++ b/packages/foam-vscode/src/features/panels/placeholders.ts @@ -118,12 +118,7 @@ export class PlaceholderTreeView extends GroupedResourcesTreeDataProvider { item.getChildren = async () => { return groupRangesByResource( this.workspace, - await createBacklinkItemsForResource( - this.workspace, - this.graph, - uri, - 'link' - ) + await createBacklinkItemsForResource(this.workspace, this.graph, uri) ); }; return item; diff --git a/packages/foam-vscode/src/features/panels/tags-explorer.spec.ts b/packages/foam-vscode/src/features/panels/tags-explorer.spec.ts index c8bb885ec..c8c630cfe 100644 --- a/packages/foam-vscode/src/features/panels/tags-explorer.spec.ts +++ b/packages/foam-vscode/src/features/panels/tags-explorer.spec.ts @@ -1,3 +1,4 @@ +/* @unit-ready */ import { createTestNote } from '../../test/test-utils'; import { cleanWorkspace, closeEditors } from '../../test/test-utils-vscode'; import { TagItem, TagsProvider } from './tags-explorer'; diff --git a/packages/foam-vscode/src/features/panels/utils/tree-view-utils.ts b/packages/foam-vscode/src/features/panels/utils/tree-view-utils.ts index f707472c9..7151baed1 100644 --- a/packages/foam-vscode/src/features/panels/utils/tree-view-utils.ts +++ b/packages/foam-vscode/src/features/panels/utils/tree-view-utils.ts @@ -6,7 +6,7 @@ import { Range } from '../../../core/model/range'; import { URI } from '../../../core/model/uri'; import { FoamWorkspace } from '../../../core/model/workspace'; import { isSome } from '../../../core/utils'; -import { getBlockFor } from '../../../core/services/markdown-parser'; +import { getBlockFor } from '../../../core/utils/md'; import { Connection, FoamGraph } from '../../../core/model/graph'; import { Logger } from '../../../core/utils/log'; import { getNoteTooltip } from '../../../services/editor'; @@ -188,24 +188,31 @@ export const groupRangesByResource = async ( return resourceItems; }; +/** + * Creates backlink items for a resource, optionally scoped to a section/block (by fragment). + * If fragment is provided, only backlinks to that section/block are included. + */ export function createBacklinkItemsForResource( workspace: FoamWorkspace, graph: FoamGraph, uri: URI, variant: 'backlink' | 'link' = 'backlink' ) { - const connections = graph + let connections; + // Note-level backlinks + connections = graph .getConnections(uri) .filter(c => c.target.asPlain().isEqual(uri)); - const backlinkItems = connections.map(async c => - ResourceRangeTreeItem.createStandardItem( + const backlinkItems = connections.map(async c => { + const item = await ResourceRangeTreeItem.createStandardItem( workspace, workspace.get(c.source), c.link.range, variant - ) - ); + ); + return item; + }); return Promise.all(backlinkItems); } @@ -218,13 +225,26 @@ export function createConnectionItemsForResource( const connections = graph.getConnections(uri).filter(c => filter(c)); const backlinkItems = connections.map(async c => { + const isBacklink = !c.source.asPlain().isEqual(uri); const item = await ResourceRangeTreeItem.createStandardItem( workspace, workspace.get(c.source), c.link.range, - c.source.asPlain().isEqual(uri) ? 'link' : 'backlink' + isBacklink ? 'backlink' : 'link' ); item.value = c; + + if (isBacklink && c.target.fragment) { + const targetResource = workspace.get(c.target.asPlain()); + if (targetResource) { + const fragment = c.target.fragment; + const section = Resource.findSection(targetResource, fragment); + if (isSome(section)) { + item.label = section.label; + } + } + } + return item; }); return Promise.all(backlinkItems); diff --git a/packages/foam-vscode/src/features/preview/blockid-preview-removal.ts b/packages/foam-vscode/src/features/preview/blockid-preview-removal.ts new file mode 100644 index 000000000..37db1706d --- /dev/null +++ b/packages/foam-vscode/src/features/preview/blockid-preview-removal.ts @@ -0,0 +1,54 @@ +import MarkdownIt from 'markdown-it'; +import Token from 'markdown-it/lib/token'; + +// Matches a block ID at the end of a block (e.g., "^my-block-id") +const blockIdRegex = /\s*(\^[-_a-zA-Z0-9]+)\s*$/; + +/** + * Markdown-it plugin for Foam block IDs (inline ^block-id syntax). + * + * - Removes block IDs from the rendered text for all block types. + * - For paragraphs and list items, cleans the block ID from the text. + */ +export function markdownItblockIdRemoval( + md: MarkdownIt, + _workspace?: any, + _parser?: any +) { + md.core.ruler.push('foam_block_id_inline', state => { + const tokens = state.tokens; + for (let i = 0; i < tokens.length; i++) { + // Look for: block_open, inline, block_close + const openToken = tokens[i]; + const inlineToken = tokens[i + 1]; + const closeToken = tokens[i + 2]; + + if ( + !inlineToken || + !closeToken || + inlineToken.type !== 'inline' || + openToken.nesting !== 1 || + closeToken.nesting !== -1 + ) { + continue; + } + + const match = inlineToken.content.match(blockIdRegex); + if (!match) { + continue; + } + + // Remove the block ID from the text content for all block types + inlineToken.content = inlineToken.content.replace(blockIdRegex, ''); + if (inlineToken.children) { + // Also clean from the last text child, which is where it will be + const lastChild = inlineToken.children[inlineToken.children.length - 1]; + if (lastChild && lastChild.type === 'text') { + lastChild.content = lastChild.content.replace(blockIdRegex, ''); + } + } + } + return true; + }); + return md; +} diff --git a/packages/foam-vscode/src/features/preview/index.ts b/packages/foam-vscode/src/features/preview/index.ts index 598979d47..6493448df 100644 --- a/packages/foam-vscode/src/features/preview/index.ts +++ b/packages/foam-vscode/src/features/preview/index.ts @@ -3,9 +3,10 @@ import * as vscode from 'vscode'; import { Foam } from '../../core/model/foam'; import { default as markdownItFoamTags } from './tag-highlight'; -import { default as markdownItWikilinkNavigation } from './wikilink-navigation'; +import { markdownItWikilinkNavigation } from './wikilink-navigation'; import { default as markdownItRemoveLinkReferences } from './remove-wikilink-references'; import { default as markdownItWikilinkEmbed } from './wikilink-embed'; +import { markdownItblockIdRemoval } from './blockid-preview-removal'; export default async function activate( context: vscode.ExtensionContext, @@ -20,6 +21,7 @@ export default async function activate( markdownItFoamTags, markdownItWikilinkNavigation, markdownItRemoveLinkReferences, + markdownItblockIdRemoval, ].reduce( (acc, extension) => extension(acc, foam.workspace, foam.services.parser), diff --git a/packages/foam-vscode/src/features/preview/tag-highlight.spec.ts b/packages/foam-vscode/src/features/preview/tag-highlight.spec.ts index 145b3515f..672ae0080 100644 --- a/packages/foam-vscode/src/features/preview/tag-highlight.spec.ts +++ b/packages/foam-vscode/src/features/preview/tag-highlight.spec.ts @@ -1,3 +1,4 @@ +/* @unit-ready */ import MarkdownIt from 'markdown-it'; import { FoamWorkspace } from '../../core/model/workspace'; import { default as markdownItFoamTags } from './tag-highlight'; diff --git a/packages/foam-vscode/src/features/preview/wikilink-embed.spec.ts b/packages/foam-vscode/src/features/preview/wikilink-embed.spec.ts index 6d0ad2021..91803e36f 100644 --- a/packages/foam-vscode/src/features/preview/wikilink-embed.spec.ts +++ b/packages/foam-vscode/src/features/preview/wikilink-embed.spec.ts @@ -1,3 +1,4 @@ +/* @unit-ready */ import MarkdownIt from 'markdown-it'; import { FoamWorkspace } from '../../core/model/workspace'; import { createMarkdownParser } from '../../core/services/markdown-parser'; @@ -5,15 +6,99 @@ import { createFile, deleteFile, withModifiedFoamConfiguration, + cleanWorkspace, + closeEditors, } from '../../test/test-utils-vscode'; import { default as markdownItWikilinkEmbed, CONFIG_EMBED_NOTE_TYPE, } from './wikilink-embed'; +import { markdownItWikilinkNavigation } from './wikilink-navigation'; +import { readFileFromFs, TEST_DATA_DIR } from '../../test/test-utils'; +import { URI } from '../../core/model/uri'; const parser = createMarkdownParser(); describe('Displaying included notes in preview', () => { + beforeEach(async () => { + await cleanWorkspace(); + await closeEditors(); + }); + + it('should embed a block from another note', async () => { + const noteWithBlockContent = await readFileFromFs( + TEST_DATA_DIR.joinPath('block-identifiers', 'note-with-block-id.md') + ); + const noteWithBlock = await createFile(noteWithBlockContent, [ + 'note-with-block.md', + ]); + + const linkingNoteContent = `![[note-with-block#^block-1]]`; + const linkingNote = await createFile(linkingNoteContent, [ + 'linking-note.md', + ]); + + const ws = new FoamWorkspace() + .set(parser.parse(noteWithBlock.uri, noteWithBlock.content)) + .set(parser.parse(linkingNote.uri, linkingNote.content)); + + await withModifiedFoamConfiguration( + CONFIG_EMBED_NOTE_TYPE, + 'content-inline', + () => { + const md = markdownItWikilinkEmbed(MarkdownIt(), ws, parser); + const result = md.render(linkingNote.content); + expect(result).toContain( + '

This is a paragraph with a block identifier. ^block-1

' + ); + expect(result).not.toContain('![[note-with-block#^block-1]]'); + } + ); + + await deleteFile(noteWithBlock.uri); + await deleteFile(linkingNote.uri); + }); + + it('should embed a block with a link inside it', async () => { + const noteAContent = '# Note A'; + const noteA = await createFile(noteAContent, ['note-a.md']); + const noteWithLinkedBlockContent = + '# Mixed Target Note\n\nHere is a paragraph with a [[note-a]]. ^para-block'; + const noteWithLinkedBlock = await createFile(noteWithLinkedBlockContent, [ + 'note-with-linked-block.md', + ]); + + const linkingNote2Content = `![[note-with-linked-block#^para-block]]`; + const linkingNote2 = await createFile(linkingNote2Content, [ + 'linking-note-2.md', + ]); + + const ws = new FoamWorkspace() + .set(parser.parse(noteA.uri, noteAContent)) + .set(parser.parse(noteWithLinkedBlock.uri, noteWithLinkedBlock.content)) + .set(parser.parse(linkingNote2.uri, linkingNote2.content)); + + await withModifiedFoamConfiguration( + CONFIG_EMBED_NOTE_TYPE, + 'content-inline', + () => { + const md = markdownItWikilinkNavigation( + markdownItWikilinkEmbed(MarkdownIt(), ws, parser), + ws + ); + const result = md.render(linkingNote2.content); + const linkHtml = `Note A`; + expect(result).toContain( + `

Here is a paragraph with a ${linkHtml}. ^para-block

` + ); + } + ); + + await deleteFile(noteA.uri); + await deleteFile(noteWithLinkedBlock.uri); + await deleteFile(linkingNote2.uri); + }); + it('should render an included note in full inline mode', async () => { const note = await createFile('This is the text of note A', [ 'preview', @@ -27,17 +112,13 @@ describe('Displaying included notes in preview', () => { const md = markdownItWikilinkEmbed(MarkdownIt(), ws, parser); expect( - md.render(`This is the root node. - - ![[note-a]]`) + md.render(`This is the root node. \n \n ![[note-a]]`) ).toMatch( - `

This is the root node.

-

This is the text of note A

-

` + `

This is the root node.

\n

This is the text of note A

\n` ); } ); - await deleteFile(note); + await deleteFile(note.uri); }); it('should render an included note in full card mode', async () => { @@ -59,7 +140,7 @@ describe('Displaying included notes in preview', () => { expect(res).toContain('This is the text of note A'); } ); - await deleteFile(note); + await deleteFile(note.uri); }); it('should render an included section in full inline mode', async () => { @@ -75,6 +156,7 @@ This is the second section of note E # Section 3 This is the third section of note E + `, ['note-e.md'] ); @@ -86,20 +168,16 @@ This is the third section of note E CONFIG_EMBED_NOTE_TYPE, 'full-inline', () => { + // markdown-it wraps the embed in a

if it's not on its own line expect( - md.render(`This is the root node. - - ![[note-e#Section 2]]`) + md.render(`This is the root node. \n\n ![[note-e#Section 2]]`) ).toMatch( - `

This is the root node.

-

Section 2

-

This is the second section of note E

-

` + `

This is the root node.

\n

Section 2

\n

This is the second section of note E

\n

\n` ); } ); - await deleteFile(note); + await deleteFile(note.uri); }); it('should render an included section in full card mode', async () => { @@ -108,11 +186,12 @@ This is the third section of note E # Section 1 This is the first section of note E -# Section 2 +# Section 2 This is the second section of note E # Section 3 This is the third section of note E + `, ['note-e-container.md'] ); @@ -135,7 +214,7 @@ This is the third section of note E } ); - await deleteFile(note); + await deleteFile(note.uri); }); it('should not render the title of a note in content inline mode', async () => { @@ -156,20 +235,18 @@ This is the first section of note E`, () => { const md = markdownItWikilinkEmbed(MarkdownIt(), ws, parser); + // markdown-it wraps the embed in a

if it's not on its own line expect( md.render(`This is the root node. ![[note-e]]`) ).toMatch( - `

This is the root node.

-

Section 1

-

This is the first section of note E

-

` + `

This is the root node.

\n

Section 1

\n

This is the first section of note E

\n

\n` ); } ); - await deleteFile(note); + await deleteFile(note.uri); }); it('should not render the title of a note in content card mode', async () => { @@ -200,7 +277,7 @@ This is the first section of note E } ); - await deleteFile(note); + await deleteFile(note.uri); }); it('should not render the section title, but still render subsection titles in content inline mode', async () => { @@ -225,21 +302,18 @@ This is the first subsection of note E () => { const md = markdownItWikilinkEmbed(MarkdownIt(), ws, parser); + // markdown-it wraps the embed in a

if it's not on its own line expect( md.render(`This is the root node. ![[note-e#Section 1]]`) ).toMatch( - `

This is the root node.

-

This is the first section of note E

-

Subsection a

-

This is the first subsection of note E

-

` + `

This is the root node.

\n

This is the first section of note E

\n

Subsection a

\n

This is the first subsection of note E

\n

\n` ); } ); - await deleteFile(note); + await deleteFile(note.uri); }); it('should not render the subsection title in content mode if you link to it and regardless of its level', async () => { @@ -261,19 +335,16 @@ This is the first subsection of note E`, () => { const md = markdownItWikilinkEmbed(MarkdownIt(), ws, parser); + // If the embed is a single paragraph, markdown-it produces a single

expect( - md.render(`This is the root node. - -![[note-e#Subsection a]]`) + md.render(`This is the root node. \n\n![[note-e#Subsection a]]`) ).toMatch( - `

This is the root node.

-

This is the first subsection of note E

-

` + `

This is the root node.

\n

This is the first subsection of note E

\n` ); } ); - await deleteFile(note); + await deleteFile(note.uri); }); it('should allow a note embedding type to be overridden if a modifier is passed in', async () => { @@ -282,11 +353,12 @@ This is the first subsection of note E`, # Section 1 This is the first section of note E -# Section 2 +# Section 2 This is the second section of note E # Section 3 This is the third section of note E + `, ['note-e.md'] ); @@ -298,6 +370,7 @@ This is the third section of note E CONFIG_EMBED_NOTE_TYPE, 'full-inline', () => { + // markdown-it wraps the embed in a

if it's not on its own line expect( md.render(`This is the root node. @@ -305,18 +378,12 @@ This is the third section of note E full![[note-e#Section 3]]`) ).toMatch( - `

This is the root node.

-

This is the second section of note E

-

-

Section 3

-

This is the third section of note E

-

-` + `

This is the root node.

\n

This is the second section of note E

\n

Section 3

\n

This is the third section of note E

\n

\n` ); } ); - await deleteFile(note); + await deleteFile(note.uri); }); it('should allow a note embedding type to be overridden if two modifiers are passed in', async () => { @@ -339,7 +406,7 @@ This is the second section of note E 'full-inline', () => { const res = md.render(`This is the root node. - + content-card![[note-e#Section 2]]`); expect(res).toContain('This is the root node'); @@ -349,7 +416,7 @@ content-card![[note-e#Section 2]]`); } ); - await deleteFile(note); + await deleteFile(note.uri); }); it('should fallback to the bare text when the note is not found', () => { @@ -377,15 +444,15 @@ content-card![[note-e#Section 2]]`); 'full-inline', () => { const md = markdownItWikilinkEmbed(MarkdownIt(), ws, parser); - expect(md.render(`This is the root node. ![[note]]`)).toMatch( - `

This is the root node.

This is the text of note A which includes ![[does-not-exist]]

-

` + expect(md.render(`This is the root node. ![[note]]`)).toBe( + `

This is the root node. This is the text of note A which includes ![[does-not-exist]]

\n` ); } ); + await deleteFile(note.uri); }); - it.skip('should display a warning in case of cyclical inclusions', async () => { + it('should display a warning in case of cyclical inclusions', async () => { const noteA = await createFile( 'This is the text of note A which includes ![[note-b]]', ['preview', 'note-a.md'] @@ -411,7 +478,195 @@ content-card![[note-e#Section 2]]`); } ); - await deleteFile(noteA); - await deleteFile(noteB); + await deleteFile(noteA.uri); + await deleteFile(noteB.uri); + }); + + describe('Block Identifiers', () => { + it('should correctly transclude a paragraph block', async () => { + const content = await readFileFromFs( + TEST_DATA_DIR.joinPath('block-identifiers', 'paragraph.md') + ); + const note = await createFile(content, ['paragraph.md']); + const ws = new FoamWorkspace().set(parser.parse(note.uri, note.content)); + const md = markdownItWikilinkEmbed(MarkdownIt(), ws, parser); + + await withModifiedFoamConfiguration( + CONFIG_EMBED_NOTE_TYPE, + 'full-inline', + () => { + expect(md.render(`![[paragraph#^p1]]`)).toMatch( + `

This is a paragraph. ^p1

\n` + ); + } + ); + await deleteFile(note.uri); + }); + + it('should correctly transclude a list item block', async () => { + const content = await readFileFromFs( + TEST_DATA_DIR.joinPath('block-identifiers', 'list.md') + ); + const note = await createFile(content, ['list.md']); + const ws = new FoamWorkspace().set(parser.parse(note.uri, note.content)); + const md = markdownItWikilinkEmbed(MarkdownIt(), ws, parser); + + await withModifiedFoamConfiguration( + CONFIG_EMBED_NOTE_TYPE, + 'full-inline', + () => { + expect(md.render(`![[list#^li1]]`)).toMatch( + `
    \n
  • list item 1 ^li1
    • \n
\n` + ); + } + ); + await deleteFile(note.uri); + }); + + it('should correctly transclude a nested list item block', async () => { + const content = await readFileFromFs( + TEST_DATA_DIR.joinPath('block-identifiers', 'list.md') + ); + const note = await createFile(content, ['list.md']); + const ws = new FoamWorkspace().set(parser.parse(note.uri, note.content)); + const md = markdownItWikilinkEmbed(MarkdownIt(), ws, parser); + + await withModifiedFoamConfiguration( + CONFIG_EMBED_NOTE_TYPE, + 'full-inline', + () => { + expect(md.render(`![[list#^nli1]]`)).toMatch( + `
    \n
  • nested list item 1 ^nli1
    • \n
\n` + ); + } + ); + await deleteFile(note.uri); + }); + + it('should correctly transclude a heading block', async () => { + const content = await readFileFromFs( + TEST_DATA_DIR.joinPath('block-identifiers', 'heading.md') + ); + const note = await createFile(content, ['heading.md']); + const ws = new FoamWorkspace().set(parser.parse(note.uri, note.content)); + const md = markdownItWikilinkEmbed(MarkdownIt(), ws, parser); + + await withModifiedFoamConfiguration( + CONFIG_EMBED_NOTE_TYPE, + 'full-inline', + () => { + expect(md.render(`![[heading#^h2]]`)).toMatch( + `

Heading 2 ^h2

\n

Some more content.

\n` + ); + } + ); + await deleteFile(note.uri); + }); + + it('should correctly transclude a code block', async () => { + const content = await readFileFromFs( + TEST_DATA_DIR.joinPath('block-identifiers', 'code-block.md') + ); + const note = await createFile(content, ['code-block.md']); + const ws = new FoamWorkspace().set(parser.parse(note.uri, note.content)); + const md = markdownItWikilinkEmbed(MarkdownIt(), ws, parser); + + await withModifiedFoamConfiguration( + CONFIG_EMBED_NOTE_TYPE, + 'full-inline', + () => { + expect(md.render(`![[code-block#^cb1]]`)).toMatch( + `
{
+  "key": "value"
+}
+
\n` + ); + } + ); + await deleteFile(note.uri); + }); + + it('should embed a block with links and keep them functional', async () => { + const noteA = await createFile('# Note A\n', ['note-a.md']); + const noteWithBlock = await createFile( + '# Note with block\n\nThis is a paragraph with a [[note-a]] and a block identifier. ^my-linked-block', + ['note-with-linked-block.md'] + ); + + const linkingNote = await createFile( + '# Linking note\n\nThis note embeds a block: ![[note-with-linked-block#^my-linked-block]]', + ['linking-note.md'] + ); + + const ws = new FoamWorkspace() + .set(parser.parse(noteA.uri, noteA.content)) + .set(parser.parse(noteWithBlock.uri, noteWithBlock.content)) + .set(parser.parse(linkingNote.uri, linkingNote.content)); + + const md = markdownItWikilinkEmbed(MarkdownIt(), ws, parser); + const result = md.render(linkingNote.content); + + expect(result).toContain('This is a paragraph with a'); + expect(result).toContain('note-a.md'); + expect(result).toContain('and a block identifier. ^my-linked-block'); + + await deleteFile(noteA.uri); + await deleteFile(noteWithBlock.uri); + await deleteFile(linkingNote.uri); + }); + }); +}); + +describe('Mixed Scenario Embed', () => { + it('should correctly embed a block from a note with mixed content', async () => { + const parser = createMarkdownParser([]); + const ws = new FoamWorkspace(); + const noteAContent = '# Note A'; + const noteA = await createFile(noteAContent, ['note-a.md']); + + const mixedTargetContent = + '# Mixed Target Note\n\nHere is a paragraph with a [[note-a]]. ^para-block\n\n- List item 1\n- List item 2 with [[note-a]] ^list-block'; + const mixedSourceContent = + '# Mixed Source Note\n\nThis note embeds a paragraph: ![[mixed-target#^para-block]]\n\nAnd this note embeds a list item: ![[mixed-target#^list-block]]'; + + const mixedTargetFile = await createFile(mixedTargetContent, [ + 'mixed-target.md', + ]); + const mixedSourceFile = await createFile(mixedSourceContent, [ + 'mixed-source.md', + ]); + + const mixedTarget = parser.parse(mixedTargetFile.uri, mixedTargetContent); + const mixedSource = parser.parse(mixedSourceFile.uri, mixedSourceContent); + const noteAResource = parser.parse(noteA.uri, noteAContent); + + ws.set(mixedTarget).set(mixedSource).set(noteAResource); + await withModifiedFoamConfiguration( + CONFIG_EMBED_NOTE_TYPE, + 'content-inline', + () => { + const md = markdownItWikilinkNavigation( + markdownItWikilinkEmbed(MarkdownIt(), ws, parser), + ws + ); + const result = md.render(mixedSourceContent); + + const linkHtml = `Note A`; + + // Check for embedded paragraph block content + expect(result).toContain( + `This note embeds a paragraph: Here is a paragraph with a ${linkHtml}. ^para-block` + ); + + // Check for embedded list block content + expect(result).toContain( + `
  • List item 2 with ${linkHtml} ^list-block
    • ` + ); + } + ); + + await deleteFile(mixedTargetFile.uri); + await deleteFile(mixedSourceFile.uri); + await deleteFile(noteA.uri); }); }); diff --git a/packages/foam-vscode/src/features/preview/wikilink-embed.ts b/packages/foam-vscode/src/features/preview/wikilink-embed.ts index a8f18a3e2..0dbf27ec1 100644 --- a/packages/foam-vscode/src/features/preview/wikilink-embed.ts +++ b/packages/foam-vscode/src/features/preview/wikilink-embed.ts @@ -6,29 +6,53 @@ import { workspace as vsWorkspace } from 'vscode'; import markdownItRegex from 'markdown-it-regex'; import { FoamWorkspace } from '../../core/model/workspace'; import { Logger } from '../../core/utils/log'; -import { Resource, ResourceParser } from '../../core/model/note'; +import { + HeadingSection, + Resource, + ResourceParser, +} from '../../core/model/note'; import { getFoamVsCodeConfig } from '../../services/config'; import { fromVsCodeUri, toVsCodeUri } from '../../utils/vsc-utils'; import { MarkdownLink } from '../../core/services/markdown-link'; import { URI } from '../../core/model/uri'; import { Position } from '../../core/model/position'; +import { Range } from '../../core/model/range'; import { TextEdit } from '../../core/services/text-edit'; import { isNone, isSome } from '../../core/utils'; +import { stripFrontMatter } from '../../core/utils/md'; import { asAbsoluteWorkspaceUri, isVirtualWorkspace, } from '../../services/editor'; +/** + * Parses a wikilink target into its note and fragment components. + * @param wikilinkTarget The full string target of the wikilink (e.g., 'my-note#my-heading'). + * @returns An object containing the noteTarget and an optional fragment. + */ +function parseWikilink(wikilinkTarget: string): { + noteTarget: string; + fragment?: string; +} { + const [noteTarget, fragment] = wikilinkTarget.split('#'); + return { noteTarget, fragment }; +} + export const WIKILINK_EMBED_REGEX = /((?:(?:full|content)-(?:inline|card)|full|content|inline|card)?!\[\[[^[\]]+?\]\])/; // we need another regex because md.use(regex, replace) only permits capturing one group // so we capture the entire possible wikilink item (ex. content-card![[note]]) using WIKILINK_EMBED_REGEX and then -// use WIKILINK_EMBED_REGEX_GROUPER to parse it into the modifier(content-card) and the wikilink(note) +// use WIKILINK_EMBED_REGEX_GROUPS to parse it into the modifier(content-card) and the wikilink(note) export const WIKILINK_EMBED_REGEX_GROUPS = /((?:\w+)|(?:(?:\w+)-(?:\w+)))?!\[\[([^[\]]+?)\]\]/; export const CONFIG_EMBED_NOTE_TYPE = 'preview.embedNoteType'; +// refsStack is used to detect and prevent cyclic embeds. let refsStack: string[] = []; +/** + * A markdown-it plugin to handle wikilink embeds (e.g., ![[note-name]]). + * It supports embedding entire notes, specific sections, or blocks with block IDs. + */ export const markdownItWikilinkEmbed = ( md: markdownit, workspace: FoamWorkspace, @@ -39,54 +63,50 @@ export const markdownItWikilinkEmbed = ( regex: WIKILINK_EMBED_REGEX, replace: (wikilinkItem: string) => { try { - const [, noteEmbedModifier, wikilink] = wikilinkItem.match( - WIKILINK_EMBED_REGEX_GROUPS - ); + const regexMatch = wikilinkItem.match(WIKILINK_EMBED_REGEX_GROUPS); + const [, noteEmbedModifier, wikilinkTarget] = regexMatch; if (isVirtualWorkspace()) { - return ` -
    - Embed not supported in virtual workspace: ![[${wikilink}]] -
    - `; + return `\n
    \n Embed not supported in virtual workspace: ![[${wikilinkTarget}]]\n
    \n `; } - const includedNote = workspace.find(wikilink); - + // Parse the wikilink to separate the note path from the fragment. + const { noteTarget, fragment } = parseWikilink(wikilinkTarget); + const includedNote = workspace.find(noteTarget); if (!includedNote) { - return `![[${wikilink}]]`; + return `![[${wikilinkTarget}]]`; } const cyclicLinkDetected = refsStack.includes( includedNote.uri.path.toLocaleLowerCase() ); - if (cyclicLinkDetected) { - return ` -
    - Cyclic link detected for wikilink: ${wikilink} -
    - Link sequence: -
      - ${refsStack.map(ref => `
    • ${ref}
      • `).join('')} -
    -
    -
    - `; + const { noteStyle } = retrieveNoteConfig(noteEmbedModifier); + const warning = `\n
    \n Cyclic link detected for wikilink: ${wikilinkTarget}\n
    \n Link sequence:\n
      \n ${refsStack + .map(ref => `
    • ${ref}
      • `) + .join('')}\n
    \n
    \n
    \n `; + return warning; } - refsStack.push(includedNote.uri.path.toLocaleLowerCase()); - const content = getNoteContent( - includedNote, - noteEmbedModifier, - parser, - workspace, - md - ); + // Extract the raw markdown for the embed + const { noteScope, noteStyle } = retrieveNoteConfig(noteEmbedModifier); + const extractor: EmbedNoteExtractor = + noteScope === 'content' ? contentExtractor : fullExtractor; + const content = extractor(includedNote, fragment, parser, workspace); + + // Render the extracted content as HTML using the correct formatter + let rendered: string; + if (noteStyle === 'card') { + rendered = cardFormatter(md.render(content), md); + } else { + rendered = inlineFormatter(content, md); + } + refsStack.pop(); - return refsStack.length === 0 ? md.render(content) : content; + return rendered; } catch (e) { + console.error(`ERROR in wikilink embed processing:`, e); Logger.error( `Error while including ${wikilinkItem} into the current document of the Preview panel`, e @@ -99,6 +119,7 @@ export const markdownItWikilinkEmbed = ( function getNoteContent( includedNote: Resource, + linkFragment: string | undefined, noteEmbedModifier: string | undefined, parser: ResourceParser, workspace: FoamWorkspace, @@ -112,39 +133,29 @@ function getNoteContent( const { noteScope, noteStyle } = retrieveNoteConfig(noteEmbedModifier); const extractor: EmbedNoteExtractor = - noteScope === 'full' - ? fullExtractor - : noteScope === 'content' - ? contentExtractor - : fullExtractor; - - const formatter: EmbedNoteFormatter = - noteStyle === 'card' - ? cardFormatter - : noteStyle === 'inline' - ? inlineFormatter - : cardFormatter; - - content = extractor(includedNote, parser, workspace); - toRender = formatter(content, md); + noteScope === 'content' ? contentExtractor : fullExtractor; + + content = extractor(includedNote, linkFragment, parser, workspace); + + // Guarantee HTML output: if the formatter returns plain text, render it as markdown + if (!/^\s* -${md.renderInline('[[' + includedNote.uri.path + ']]')}
    -Embed for attachments is not supported -`; + content = `> [[${includedNote.uri.path}]]\n>\n> Embed for attachments is not supported`; toRender = md.render(content); break; case 'image': - content = `
    ${md.render( - `![](${md.normalizeLink(includedNote.uri.path)})` - )}
    `; + content = `![](${md.normalizeLink(includedNote.uri.path)})`; toRender = md.render(content); break; default: - toRender = content; + toRender = md.render(content); } return toRender; @@ -170,9 +181,13 @@ function withLinksRelativeToWorkspaceRoot( return null; } const pathFromRoot = asAbsoluteWorkspaceUri(resource.uri).path; - return MarkdownLink.createUpdateLinkEdit(link, { + const update: { target: string; text?: string } = { target: pathFromRoot, - }); + }; + if (!info.alias) { + update.text = info.target; + } + return MarkdownLink.createUpdateLinkEdit(link, update); }) .filter(linkEdits => !isNone(linkEdits)) .sort((a, b) => Position.compareTo(b.range.start, a.range.start)); @@ -196,10 +211,11 @@ export function retrieveNoteConfig(explicitModifier: string | undefined): { noteScope = explicitModifier; } else if (['card', 'inline'].includes(explicitModifier)) { noteStyle = explicitModifier; - } else { + } else if (explicitModifier.includes('-')) { [noteScope, noteStyle] = explicitModifier.split('-'); } } + return { noteScope, noteStyle }; } @@ -208,60 +224,143 @@ export function retrieveNoteConfig(explicitModifier: string | undefined): { */ export type EmbedNoteExtractor = ( note: Resource, + linkFragment: string | undefined, parser: ResourceParser, workspace: FoamWorkspace ) => string; +/** + * Extracts the full content of a note or a specific section/block. + * For sections, it includes the heading itself. + */ function fullExtractor( note: Resource, + linkFragment: string | undefined, parser: ResourceParser, workspace: FoamWorkspace ): string { let noteText = readFileSync(note.uri.toFsPath()).toString(); - const section = Resource.findSection(note, note.uri.fragment); + + // Find the specific section or block being linked to, if a fragment is provided. + const section = linkFragment + ? Resource.findSection(note, linkFragment) + : null; + if (isSome(section)) { - const rows = noteText.split('\n'); - noteText = rows - .slice(section.range.start.line, section.range.end.line) - .join('\n'); + if (section.type === 'heading') { + // For headings, extract all content from that heading to the next. + let rows = noteText.split(/\r?\n/); + // Find the next heading after this one, regardless of level + let nextHeadingLine = rows.length; + for (let i = section.range.start.line + 1; i < rows.length; i++) { + // Find the next heading of the same or higher level + const nextHeading = note.sections.find(s => { + if (s.type === 'heading') { + return ( + s.range.start.line === i && + s.level <= (section as HeadingSection).level + ); + } + return false; + }); + if (nextHeading) { + nextHeadingLine = i; + break; + } + } + let slicedRows = rows.slice(section.range.start.line, nextHeadingLine); + noteText = slicedRows.join('\n'); + } else { + // For block-level embeds (paragraphs, list items with a ^block-id), + // extract the content precisely using the range from the parser. + const rows = noteText.split(/\r?\n/); + noteText = rows + .slice(section.range.start.line, section.range.end.line + 1) + .join('\n'); + } + } else { + // No fragment: transclude the whole note (excluding frontmatter if present) + noteText = stripFrontMatter(noteText); } + noteText = withLinksRelativeToWorkspaceRoot( note.uri, noteText, parser, workspace ); + return noteText; } +/** + * Extracts the content of a note, excluding the main title. + * For sections, it extracts the content *under* the heading. + */ function contentExtractor( note: Resource, + linkFragment: string | undefined, parser: ResourceParser, workspace: FoamWorkspace ): string { let noteText = readFileSync(note.uri.toFsPath()).toString(); - let section = Resource.findSection(note, note.uri.fragment); - if (!note.uri.fragment) { - // if there's no fragment(section), the wikilink is linking to the entire note, - // in which case we need to remove the title. We could just use rows.shift() - // but should the note start with blank lines, it will only remove the first blank line - // leaving the title - // A better way is to find where the actual title starts by assuming it's at section[0] - // then we treat it as the same case as link to a section + + // Find the specific section or block being linked to. + let section = Resource.findSection(note, linkFragment); + + if (!linkFragment) { + // If no fragment is provided, default to the first section (usually the main title) + // to extract the content of the note, excluding the title. section = note.sections.length ? note.sections[0] : null; } - let rows = noteText.split('\n'); + if (isSome(section)) { - rows = rows.slice(section.range.start.line, section.range.end.line); + if (section.type === 'heading') { + // For headings, extract the content *under* the heading. + let rows = noteText.split(/\r?\n/); + let endOfSectionLine = rows.length; + for (let i = section.range.start.line + 1; i < rows.length; i++) { + // Find the next heading of the same or higher level + const nextHeading = note.sections.find(s => { + if (s.type === 'heading') { + return ( + s.range.start.line === i && + s.level <= (section as HeadingSection).level + ); + } + return false; + }); + if (nextHeading) { + endOfSectionLine = i; + break; + } + } + noteText = rows + .slice(section.range.start.line + 1, endOfSectionLine) + .join('\n'); + } else { + // For block-level embeds (e.g., a list item with a ^block-id), + // extract the content of just that block using its range. + const rows = noteText.split(/\r?\n/); + noteText = rows + .slice(section.range.start.line, section.range.end.line + 1) + .join('\n'); + } + } else { + // If no fragment, or fragment not found as a section, + // treat as content of the entire note (excluding title) + let rows = noteText.split(/\r?\n/); + rows.shift(); // Remove the title + noteText = rows.join('\n'); } - rows.shift(); - noteText = rows.join('\n'); + noteText = withLinksRelativeToWorkspaceRoot( note.uri, noteText, parser, workspace ); + return noteText; } @@ -271,11 +370,36 @@ function contentExtractor( export type EmbedNoteFormatter = (content: string, md: markdownit) => string; function cardFormatter(content: string, md: markdownit): string { - return `
    \n\n${content}\n\n
    `; + const result = `
    + +${content} + +
    `; + + return result; } function inlineFormatter(content: string, md: markdownit): string { - return content; + const tokens = md.parse(content.trim(), {}); + + // Optimization: If the content is just a single paragraph, render only its + // inline content. This prevents wrapping the embed in an extra, unnecessary

    tag, + // which can cause layout issues. + if ( + tokens.length === 3 && + tokens[0].type === 'paragraph_open' && + tokens[1].type === 'inline' && + tokens[2].type === 'paragraph_close' + ) { + // Render only the inline content to prevent double

    tags. + // The parent renderer will wrap this in

    tags as needed. + const result = md.renderer.render(tokens[1].children, md.options, {}); + return result; + } + + const result = md.render(content); + // For more complex content (headings, lists, etc.), render as a full block. + return result; } export default markdownItWikilinkEmbed; diff --git a/packages/foam-vscode/src/features/preview/wikilink-navigation.spec.ts b/packages/foam-vscode/src/features/preview/wikilink-navigation.spec.ts index 79e4ed16f..bc5e3c78d 100644 --- a/packages/foam-vscode/src/features/preview/wikilink-navigation.spec.ts +++ b/packages/foam-vscode/src/features/preview/wikilink-navigation.spec.ts @@ -1,34 +1,57 @@ +import * as vscode from 'vscode'; import MarkdownIt from 'markdown-it'; import { FoamWorkspace } from '../../core/model/workspace'; import { createTestNote } from '../../test/test-utils'; -import { getUriInWorkspace } from '../../test/test-utils-vscode'; -import { default as markdownItWikilinkNavigation } from './wikilink-navigation'; +import { markdownItWikilinkNavigation } from './wikilink-navigation'; import { default as markdownItRemoveLinkReferences } from './remove-wikilink-references'; +import { URI } from '../../core/model/uri'; describe('Link generation in preview', () => { + const workspaceRoot = URI.file('/path/to/workspace'); + const workspaceRootVsCode = vscode.Uri.file('/path/to/workspace'); + + beforeEach(() => { + jest + .spyOn(vscode.workspace, 'asRelativePath') + .mockImplementation((pathOrUri: string | vscode.Uri) => { + const path = + pathOrUri instanceof vscode.Uri + ? pathOrUri.path + : pathOrUri.toString(); + if (path.startsWith(workspaceRootVsCode.path)) { + // get path relative to workspace root, remove leading slash + return path.substring(workspaceRootVsCode.path.length + 1); + } + return path; + }); + }); + + afterEach(() => { + jest.restoreAllMocks(); + }); + const noteA = createTestNote({ - uri: './path/to/note-a.md', - // TODO: this should really just be the workspace folder, use that once #806 is fixed - root: getUriInWorkspace('just-a-ref.md'), + uri: '/path/to/workspace/note-a.md', title: 'My note title', links: [{ slug: 'placeholder' }], }); const noteB = createTestNote({ - uri: './path2/to/note-b.md', - root: getUriInWorkspace('just-a-ref.md'), + uri: '/path/to/workspace/path2/to/note-b.md', title: 'My second note', - sections: ['sec1', 'sec2'], + sections: [ + { label: 'sec1', level: 1 }, + { label: 'sec2', level: 1 }, + ], }); const ws = new FoamWorkspace().set(noteA).set(noteB); - const md = [ - markdownItWikilinkNavigation, - markdownItRemoveLinkReferences, - ].reduce((acc, extension) => extension(acc, ws), MarkdownIt()); + const md = MarkdownIt(); + markdownItWikilinkNavigation(md, ws, { root: workspaceRootVsCode }); + markdownItRemoveLinkReferences(md, ws); it('generates a link to a note using the note title as link', () => { expect(md.render(`[[note-a]]`)).toEqual( - `

    ${noteA.title}

    \n` + `

    ${noteA.title}

    \n` ); }); @@ -48,7 +71,7 @@ describe('Link generation in preview', () => { const note = `[[note-a]] [note-a]: "Note A"`; expect(md.render(note)).toEqual( - `

    ${noteA.title}\n[note-a]: <note-a.md> "Note A"

    \n` + `

    ${noteA.title}\n[note-a]: <note-a.md> "Note A"

    \n` ); }); diff --git a/packages/foam-vscode/src/features/preview/wikilink-navigation.ts b/packages/foam-vscode/src/features/preview/wikilink-navigation.ts index 7e85aab8d..88f5cccf7 100644 --- a/packages/foam-vscode/src/features/preview/wikilink-navigation.ts +++ b/packages/foam-vscode/src/features/preview/wikilink-navigation.ts @@ -11,64 +11,135 @@ import { isEmpty } from 'lodash'; import { toSlug } from '../../utils/slug'; import { isNone } from '../../core/utils'; +/** + * A markdown-it plugin that converts [[wikilinks]] to navigable links in the Markdown preview. + * It handles links to notes, sections, and block IDs, generating the correct hrefs + * for navigation within the VS Code preview panel. + * + * @param md The markdown-it instance. + * @param workspace The Foam workspace to resolve links against. + * @param options Optional configuration. + */ export const markdownItWikilinkNavigation = ( md: markdownit, - workspace: FoamWorkspace + workspace: FoamWorkspace, + options?: { root?: vscode.Uri } ) => { return md.use(markdownItRegex, { name: 'connect-wikilinks', + // Regex to match a wikilink, ensuring it's not an image/embed (which starts with '!') regex: /(?=[^!])\[\[([^[\]]+?)\]\]/, + // The replacement function that turns a matched wikilink string into an HTML tag. replace: (wikilink: string) => { try { + // Deconstruct the wikilink into its constituent parts. const { target, section, alias } = MarkdownLink.analyzeLink({ rawText: '[[' + wikilink + ']]', type: 'wikilink', range: Range.create(0, 0), isEmbed: false, }); - const formattedSection = section ? `#${section}` : ''; - const linkSection = section ? `#${toSlug(section)}` : ''; - const label = isEmpty(alias) ? `${target}${formattedSection}` : alias; - // [[#section]] links + // Case 1: The wikilink points to a section/block in the *current* file. if (target.length === 0) { - // we don't have a good way to check if the section exists within the - // open file, so we just create a regular link for it - return getResourceLink(section, linkSection, label); + if (section) { + // For block IDs (^block-id), the slug is the ID itself. For headings, it's a slugified version. + const slug = section.startsWith('^') + ? section.substring(1) + : toSlug(section); + const linkText = alias || `#${section}`; + const title = alias || section; + // The href is just the fragment identifier. + return getResourceLink(title, `#${slug}`, linkText); + } + // If there's no target and no section, it's a malformed link. Return as is. + return `[[${wikilink}]]`; } + // Case 2: The wikilink points to another note. const resource = workspace.find(target); + + // If the target note doesn't exist, create a "placeholder" link. if (isNone(resource)) { - return getPlaceholderLink(label); + const linkText = alias || wikilink; + return getPlaceholderLink(linkText); } - const resourceLabel = isEmpty(alias) - ? `${resource.title}${formattedSection}` - : alias; - const resourceLink = `/${vscode.workspace.asRelativePath( + // If the target note exists, construct the link to it. + // The base href points to the file path of the target resource. + const href = `/${vscode.workspace.asRelativePath( toVsCodeUri(resource.uri), false )}`; - return getResourceLink( - `${resource.title}${formattedSection}`, - `${resourceLink}${linkSection}`, - resourceLabel - ); + + let linkTitle = resource.title; + let finalHref = href; + + // If the link includes a section or block ID part (e.g., [[note#section]] or [[note#^block-id]]) + if (section) { + linkTitle += `#${section}`; + // Find the corresponding section or block in the target resource. + // This lookup works for both heading labels (by comparing slugs) and block IDs (by direct match). + const foundSection = resource.sections.find( + s => toSlug(s.label) === toSlug(section) || s.blockId === section + ); + + let fragment; + if (foundSection) { + switch (foundSection.type) { + case 'heading': + // If the link points to a heading, the fragment is the heading's generated ID. + fragment = foundSection.id; + break; + case 'block': { + // For block ID links, find the closest preceding heading section to use as the anchor. + // This ensures navigation scrolls to the most relevant context in the preview, not just the block. + const parentHeading = resource.sections + .filter( + s => + s.type === 'heading' && + s.range.start.line < foundSection.range.start.line + ) + // Sort headings by line number descending to find the closest one *before* the block. + .sort((a, b) => b.range.start.line - a.range.start.line)[0]; + + // Use the parent heading's ID if found; otherwise, fall back to a slug of the block ID. + fragment = parentHeading ? parentHeading.id : toSlug(section); + break; + } + } + } else { + // If no specific section is found, fall back to a slug of the section identifier. + fragment = toSlug(section); + } + // Append the fragment to the base href. + finalHref += `#${fragment}`; + } + + // The visible text of the link is the alias if provided, otherwise the generated link title. + const linkText = alias || linkTitle; + + return getResourceLink(linkTitle, finalHref, linkText); } catch (e) { - Logger.error( - `Error while creating link for [[${wikilink}]] in Preview panel`, - e - ); + Logger.error('Error while parsing wikilink', e); + // Fallback for any errors during processing. return getPlaceholderLink(wikilink); } }, }); }; -const getPlaceholderLink = (content: string) => - `${content}`; - -const getResourceLink = (title: string, link: string, label: string) => - `${label}`; +/** + * Generates an HTML tag for a valid, resolved link. + * Includes data-href for compatibility with VS Code's link-following logic. + */ +function getResourceLink(title: string, href: string, text: string) { + return `${text}`; +} -export default markdownItWikilinkNavigation; +/** + * Generates a disabled-style HTML tag for a link to a non-existent note. + */ +function getPlaceholderLink(text: string) { + return `${text}`; +} diff --git a/packages/foam-vscode/src/features/refactor.spec.ts b/packages/foam-vscode/src/features/refactor.spec.ts index 9c77cd191..c0af29e40 100644 --- a/packages/foam-vscode/src/features/refactor.spec.ts +++ b/packages/foam-vscode/src/features/refactor.spec.ts @@ -53,7 +53,7 @@ describe('Note rename sync', () => { expect((await readFile(noteC.uri)).trim()).toEqual( `Link to [[${newName}]] from note C.` ); - }, 1000); + }, 3000); await deleteFile(newUri); await deleteFile(noteB.uri); @@ -89,7 +89,7 @@ describe('Note rename sync', () => { expect(doc.getText().trim()).toEqual( `Link to [[first/note-b]] from note C.` ); - }); + }, 3000); await deleteFile(newUri); await deleteFile(noteC.uri); }); @@ -126,8 +126,8 @@ describe('Note rename sync', () => { }); it('should keep the alias in wikilinks', async () => { - const noteA = await createFile(`Content of note A`); - const noteB = await createFile(`Link to [[${noteA.name}|Alias]]`); + const noteA = await createFile(`Content of note A`, ['note-a.md']); + const noteB = await createFile(`Link to [[note-a|Alias]]`, ['note-b.md']); const { doc } = await showInEditor(noteB.uri); diff --git a/packages/foam-vscode/src/features/refactor.ts b/packages/foam-vscode/src/features/refactor.ts index 334d605cc..d094fb25c 100644 --- a/packages/foam-vscode/src/features/refactor.ts +++ b/packages/foam-vscode/src/features/refactor.ts @@ -33,12 +33,14 @@ export default async function activate( const { target } = MarkdownLink.analyzeLink(connection.link); switch (connection.link.type) { case 'wikilink': { + const { section } = MarkdownLink.analyzeLink(connection.link); const identifier = foam.workspace.getIdentifier( fromVsCodeUri(newUri), [fromVsCodeUri(oldUri)] ); const edit = MarkdownLink.createUpdateLinkEdit(connection.link, { target: identifier, + section: section, }); renameEdits.replace( toVsCodeUri(connection.source), @@ -53,8 +55,9 @@ export default async function activate( : fromVsCodeUri(newUri).relativeTo( connection.source.getDirectory() ).path; + const { section } = MarkdownLink.analyzeLink(connection.link); const edit = MarkdownLink.createUpdateLinkEdit(connection.link, { - target: path, + target: section ? `${path}#${section}` : path, }); renameEdits.replace( toVsCodeUri(connection.source), diff --git a/packages/foam-vscode/src/features/wikilink-diagnostics.spec.ts b/packages/foam-vscode/src/features/wikilink-diagnostics.spec.ts index 1cf85eea9..67a67b681 100644 --- a/packages/foam-vscode/src/features/wikilink-diagnostics.spec.ts +++ b/packages/foam-vscode/src/features/wikilink-diagnostics.spec.ts @@ -1,12 +1,15 @@ import * as vscode from 'vscode'; import { createMarkdownParser } from '../core/services/markdown-parser'; import { FoamWorkspace } from '../core/model/workspace'; +import { URI } from '../core/model/uri'; import { cleanWorkspace, closeEditors, createFile, + deleteFile, showInEditor, } from '../test/test-utils-vscode'; +import { readFileFromFs, TEST_DATA_DIR } from '../test/test-utils'; import { toVsCodeUri } from '../utils/vsc-utils'; import { updateDiagnostics } from './wikilink-diagnostics'; @@ -188,6 +191,146 @@ Content of section 2 }); }); +describe('Block Identifier diagnostics', () => { + it('should show nothing when the block id is correct', async () => { + const noteWithBlockId = await createFile( + '# Note with block id\n\nThis is a paragraph. ^block-1', + [ + 'packages', + 'foam-vscode', + 'test-data', + 'block-identifiers', + 'note-with-block-id.md', + ] + ); + const linkingNote = await createFile( + `Link to [[${noteWithBlockId.name}#^block-1]]`, + [ + 'packages', + 'foam-vscode', + 'test-data', + 'block-identifiers', + 'linking-to-valid-block.md', + ] + ); + + const parser = createMarkdownParser([]); + const ws = new FoamWorkspace() + .set(parser.parse(noteWithBlockId.uri, noteWithBlockId.content)) + .set(parser.parse(linkingNote.uri, linkingNote.content)); + + await showInEditor(linkingNote.uri); + + const collection = vscode.languages.createDiagnosticCollection('foam-test'); + updateDiagnostics( + ws, + parser, + vscode.window.activeTextEditor.document, + collection + ); + expect(countEntries(collection)).toEqual(0); + }); + + it('should show a warning when the block id is incorrect', async () => { + const noteWithBlockId = await createFile( + '# Note with block id\n\nThis is a paragraph. ^block-1', + [ + 'packages', + 'foam-vscode', + 'test-data', + 'block-identifiers', + 'note-with-block-id.md', + ] + ); + const linkContent = `[[${noteWithBlockId.name}#^non-existent-block]]`; + const fileContent = `Link to ${linkContent}`; + const linkingNote = await createFile(fileContent, [ + 'packages', + 'foam-vscode', + 'test-data', + 'block-identifiers', + 'linking-to-invalid-block.md', + ]); + + const parser = createMarkdownParser([]); + const ws = new FoamWorkspace() + .set(parser.parse(noteWithBlockId.uri, noteWithBlockId.content)) + .set(parser.parse(linkingNote.uri, linkingNote.content)); + + await showInEditor(linkingNote.uri); + + const collection = vscode.languages.createDiagnosticCollection('foam-test'); + updateDiagnostics( + ws, + parser, + vscode.window.activeTextEditor.document, + collection + ); + expect(countEntries(collection)).toEqual(1); + const items = collection.get(toVsCodeUri(linkingNote.uri)); + expect(items[0].range).toEqual(new vscode.Range(0, 28, 0, 50)); + expect(items[0].severity).toEqual(vscode.DiagnosticSeverity.Warning); + expect(items[0].relatedInformation.map(info => info.message)).toEqual([ + 'Note with block id', + '^block-1', + ]); + }); +}); + +describe('Mixed Scenario Diagnostics', () => { + it('should report a warning for a non-existent block but not for valid links', async () => { + const parser = createMarkdownParser([]); + const ws = new FoamWorkspace(); + + const mixedTargetContent = await readFileFromFs( + TEST_DATA_DIR.joinPath('block-identifiers', 'mixed-target.md') + ); + const mixedOtherContent = await readFileFromFs( + TEST_DATA_DIR.joinPath('block-identifiers', 'mixed-other.md') + ); + const mixedSourceContent = await readFileFromFs( + TEST_DATA_DIR.joinPath('block-identifiers', 'mixed-source.md') + ); + + const mixedTargetFile = await createFile(mixedTargetContent, [ + 'mixed-target.md', + ]); + const mixedOtherFile = await createFile(mixedOtherContent, [ + 'mixed-other.md', + ]); + const mixedSourceFile = await createFile(mixedSourceContent, [ + 'mixed-source.md', + ]); + + const mixedTarget = parser.parse(mixedTargetFile.uri, mixedTargetContent); + const mixedOther = parser.parse(mixedOtherFile.uri, mixedOtherContent); + const mixedSource = parser.parse(mixedSourceFile.uri, mixedSourceContent); + + ws.set(mixedTarget).set(mixedOther).set(mixedSource); + + await showInEditor(mixedSource.uri); + + const collection = vscode.languages.createDiagnosticCollection('foam-test'); + updateDiagnostics( + ws, + parser, + vscode.window.activeTextEditor.document, + collection + ); + + expect(countEntries(collection)).toEqual(1); + const items = collection.get(toVsCodeUri(mixedSource.uri)); + // The warning should be for [[mixed-target#^no-such-block]] + // which is on line 9 (index 8) of mixed-source.md + expect(items[0].range).toEqual(new vscode.Range(8, 44, 8, 61)); + expect(items[0].message).toContain('Cannot find section'); + + await deleteFile(mixedTargetFile.uri); + await deleteFile(mixedOtherFile.uri); + await deleteFile(mixedSourceFile.uri); + }); +}); + const countEntries = (collection: vscode.DiagnosticCollection): number => { let count = 0; collection.forEach((i, diagnostics) => { diff --git a/packages/foam-vscode/src/features/wikilink-diagnostics.ts b/packages/foam-vscode/src/features/wikilink-diagnostics.ts index 01a8c4056..086561ab1 100644 --- a/packages/foam-vscode/src/features/wikilink-diagnostics.ts +++ b/packages/foam-vscode/src/features/wikilink-diagnostics.ts @@ -1,7 +1,14 @@ +/** + * @file Provides diagnostics for wikilinks in markdown files. + * This includes: + * - Detecting ambiguous links (when an identifier can resolve to multiple notes). + * - Detecting broken section links (when the note exists but the #section does not). + * - Providing Quick Fixes (Code Actions) to resolve these issues. + */ import { debounce } from 'lodash'; import * as vscode from 'vscode'; import { Foam } from '../core/model/foam'; -import { Resource, ResourceParser } from '../core/model/note'; +import { Resource, ResourceParser, ResourceLink } from '../core/model/note'; import { Range } from '../core/model/range'; import { FoamWorkspace } from '../core/model/workspace'; import { MarkdownLink } from '../core/services/markdown-link'; @@ -13,7 +20,16 @@ import { } from '../utils/vsc-utils'; import { isNone } from '../core/utils'; +/** + * Diagnostic code for an ambiguous link identifier. + * Used when a wikilink could refer to more than one note. + */ const AMBIGUOUS_IDENTIFIER_CODE = 'ambiguous-identifier'; + +/** + * Diagnostic code for an unknown section in a wikilink. + * Used when the note exists, but the section identifier (e.g., #my-section) does not. + */ const UNKNOWN_SECTION_CODE = 'unknown-section'; interface FoamCommand { @@ -28,6 +44,11 @@ interface FindIdentifierCommandArgs { amongst: vscode.Uri[]; } +/** + * A command that computes the shortest unambiguous identifier for a target URI + * among a set of potential targets and replaces the text in the editor. + * Used by the Quick Fix for ambiguous links. + */ const FIND_IDENTIFIER_COMMAND: FoamCommand = { name: 'foam:compute-identifier', execute: async ({ target, amongst, range, defaultExtension }) => { @@ -53,6 +74,10 @@ interface ReplaceTextCommandArgs { value: string; } +/** + * A generic command that replaces a range of text in the active editor with a new value. + * Used by the Quick Fix for unknown sections. + */ const REPLACE_TEXT_COMMAND: FoamCommand = { name: 'foam:replace-text', execute: async ({ range, value }) => { @@ -98,7 +123,7 @@ export default async function activate( }), vscode.languages.registerCodeActionsProvider( 'markdown', - new IdentifierResolver(foam.workspace.defaultExtension), + new IdentifierResolver(foam.workspace, foam.workspace.defaultExtension), { providedCodeActionKinds: IdentifierResolver.providedCodeActionKinds, } @@ -114,6 +139,14 @@ export default async function activate( ); } +/** + * Analyzes the current document for ambiguous or broken wikilinks and generates + * corresponding diagnostics in the editor. + * @param workspace The Foam workspace, used to resolve link targets. + * @param parser The resource parser, used to get links from the document text. + * @param document The document to analyze. + * @param collection The diagnostic collection to update. + */ export function updateDiagnostics( workspace: FoamWorkspace, parser: ResourceParser, @@ -121,134 +154,262 @@ export function updateDiagnostics( collection: vscode.DiagnosticCollection ): void { collection.clear(); - const result = []; - if (document && document.languageId === 'markdown') { - const resource = parser.parse( - fromVsCodeUri(document.uri), - document.getText() - ); + if (!document || document.languageId !== 'markdown') { + return; + } - for (const link of resource.links) { - if (link.type === 'wikilink') { - const { target, section } = MarkdownLink.analyzeLink(link); - const targets = workspace.listByIdentifier(target); - if (targets.length > 1) { - result.push({ - code: AMBIGUOUS_IDENTIFIER_CODE, - message: 'Resource identifier is ambiguous', - range: toVsCodeRange(link.range), - severity: vscode.DiagnosticSeverity.Warning, - source: 'Foam', - relatedInformation: targets.map( - t => - new vscode.DiagnosticRelatedInformation( - new vscode.Location( - toVsCodeUri(t.uri), - new vscode.Position(0, 0) - ), - `Possible target: ${vscode.workspace.asRelativePath( - toVsCodeUri(t.uri) - )}` - ) - ), - }); - } - if (section && targets.length === 1) { - const resource = targets[0]; - if (isNone(Resource.findSection(resource, section))) { - const range = Range.create( - link.range.start.line, - link.range.start.character + target.length + 2, - link.range.end.line, - link.range.end.character - ); - result.push({ - code: UNKNOWN_SECTION_CODE, - message: `Cannot find section "${section}" in document, available sections are:`, - range: toVsCodeRange(range), - severity: vscode.DiagnosticSeverity.Warning, - source: 'Foam', - relatedInformation: resource.sections.map( - b => - new vscode.DiagnosticRelatedInformation( - new vscode.Location( - toVsCodeUri(resource.uri), - toVsCodePosition(b.range.start) - ), - b.label - ) - ), - }); - } - } - } + const resource = parser.parse( + fromVsCodeUri(document.uri), + document.getText() + ); + + const diagnostics = resource.links.flatMap(link => { + if (link.type !== 'wikilink') { + return []; + } + const { target, section } = MarkdownLink.analyzeLink(link); + const targets = workspace.listByIdentifier(target); + + if (targets.length > 1) { + return [createAmbiguousIdentifierDiagnostic(link, targets)]; } - if (result.length > 0) { - collection.set(document.uri, result); + if (section && targets.length === 1) { + const targetResource = targets[0]; + if (isNone(Resource.findSection(targetResource, section))) { + return [ + createUnknownSectionDiagnostic(link, target, section, targetResource), + ]; + } } + return []; + }); + + if (diagnostics.length > 0) { + collection.set(document.uri, diagnostics); } } +/** + * Creates a VS Code Diagnostic for an ambiguous wikilink identifier. + * @param link The wikilink that is ambiguous. + * @param targets The list of potential resources the link could target. + * @returns A `vscode.Diagnostic` object. + */ +function createAmbiguousIdentifierDiagnostic( + link: ResourceLink, + targets: Resource[] +): vscode.Diagnostic { + return { + code: AMBIGUOUS_IDENTIFIER_CODE, + message: 'Resource identifier is ambiguous', + range: toVsCodeRange(link.range), + severity: vscode.DiagnosticSeverity.Warning, + source: 'Foam', + relatedInformation: targets.map( + t => + new vscode.DiagnosticRelatedInformation( + new vscode.Location(toVsCodeUri(t.uri), new vscode.Position(0, 0)), + `Possible target: ${vscode.workspace.asRelativePath( + toVsCodeUri(t.uri) + )}` + ) + ), + }; +} + +/** + * Creates a VS Code Diagnostic for a wikilink pointing to a non-existent section. + * @param link The wikilink containing the broken section reference. + * @param target The string identifier of the target note. + * @param section The string identifier of the (non-existent) section. + * @param resource The target resource where the section was not found. + * @returns A `vscode.Diagnostic` object. + */ +function createUnknownSectionDiagnostic( + link: ResourceLink, + target: string, + section: string, + resource: Resource +): vscode.Diagnostic { + const range = Range.create( + link.range.start.line, + link.range.start.character + target.length + 2, + link.range.end.line, + link.range.end.character + ); + return { + code: UNKNOWN_SECTION_CODE, + message: `Cannot find section "${section}" in document, available sections are:`, + range: toVsCodeRange(range), + severity: vscode.DiagnosticSeverity.Warning, + source: 'Foam', + relatedInformation: createSectionSuggestions(resource), + }; +} + +/** + * Generates a list of suggested sections from a resource to be displayed + * as related information in a diagnostic. + * This helps the user see the available, valid sections in a note. + * @param resource The resource to generate suggestions from. + * @returns An array of `vscode.DiagnosticRelatedInformation` objects. + */ +function createSectionSuggestions( + resource: Resource +): vscode.DiagnosticRelatedInformation[] { + return resource.sections.flatMap(s => { + const infos: vscode.DiagnosticRelatedInformation[] = []; + const location = new vscode.Location( + toVsCodeUri(resource.uri), + toVsCodePosition(s.range.start) + ); + switch (s.type) { + case 'heading': + if (s.id) { + infos.push( + new vscode.DiagnosticRelatedInformation(location, s.label) // Use s.label for heading suggestions, as Quick Fix uses this + ); + } + if (s.blockId) { + infos.push( + new vscode.DiagnosticRelatedInformation(location, s.blockId) // Use s.blockId for block IDs (including caret) + ); + } + break; + case 'block': + infos.push( + new vscode.DiagnosticRelatedInformation(location, s.blockId) // For blocks, only blockId is relevant + ); + break; + } + return infos; + }); +} + +/** + * Provides Code Actions (Quick Fixes) for the diagnostics created by this file. + */ export class IdentifierResolver implements vscode.CodeActionProvider { public static readonly providedCodeActionKinds = [ vscode.CodeActionKind.QuickFix, ]; - constructor(private defaultExtension: string) {} + constructor( + private workspace: FoamWorkspace, + private defaultExtension: string + ) {} + /** + * This method is called by VS Code when the user's cursor is on a diagnostic. + * It returns a list of applicable Quick Fixes. + */ provideCodeActions( document: vscode.TextDocument, range: vscode.Range | vscode.Selection, context: vscode.CodeActionContext, token: vscode.CancellationToken ): vscode.CodeAction[] { - return context.diagnostics.reduce((acc, diagnostic) => { - if (diagnostic.code === AMBIGUOUS_IDENTIFIER_CODE) { - const res: vscode.CodeAction[] = []; - const uris = diagnostic.relatedInformation.map( - info => info.location.uri - ); - for (const item of diagnostic.relatedInformation) { - res.push( - createFindIdentifierCommand( - diagnostic, - item.location.uri, - this.defaultExtension, - uris - ) - ); - } - return [...acc, ...res]; - } - if (diagnostic.code === UNKNOWN_SECTION_CODE) { - const res: vscode.CodeAction[] = []; - const sections = diagnostic.relatedInformation.map( - info => info.message - ); - for (const section of sections) { - res.push(createReplaceSectionCommand(diagnostic, section)); - } - return [...acc, ...res]; + return context.diagnostics.flatMap(diagnostic => { + switch (diagnostic.code) { + case AMBIGUOUS_IDENTIFIER_CODE: + return this.createAmbiguousIdentifierActions(diagnostic); + case UNKNOWN_SECTION_CODE: + return this.createUnknownSectionActions(diagnostic); + default: + return []; } - return acc; - }, [] as vscode.CodeAction[]); + }); + } + + /** + * Creates the set of Quick Fixes for an `AMBIGUOUS_IDENTIFIER_CODE` diagnostic. + * This generates one Code Action for each potential target file. + */ + private createAmbiguousIdentifierActions( + diagnostic: vscode.Diagnostic + ): vscode.CodeAction[] { + const uris = diagnostic.relatedInformation.map(info => info.location.uri); + return diagnostic.relatedInformation.map(item => + createFindIdentifierCommand( + diagnostic, + item.location.uri, + this.defaultExtension, + uris + ) + ); + } + + /** + * Creates the set of Quick Fixes for an `UNKNOWN_SECTION_CODE` diagnostic. + * This generates one Code Action for each valid section in the target file. + */ + private createUnknownSectionActions( + diagnostic: vscode.Diagnostic + ): vscode.CodeAction[] { + const sectionIds = diagnostic.relatedInformation.map(info => info.message); + return sectionIds + .map(sectionId => + createReplaceSectionCommand(diagnostic, sectionId, this.workspace) + ) + .filter((action): action is vscode.CodeAction => action !== null); } } +/** + * Creates a Code Action to fix a broken section link by replacing it with a valid one. + * @param diagnostic The `UNKNOWN_SECTION_CODE` diagnostic. + * @param sectionId The ID of a valid section to suggest as a replacement. + * @param workspace The Foam workspace. + * @returns A `vscode.CodeAction` or `null` if the target resource can't be found. + */ const createReplaceSectionCommand = ( diagnostic: vscode.Diagnostic, - section: string -): vscode.CodeAction => { + sectionId: string, + workspace: FoamWorkspace +): vscode.CodeAction | null => { + // Get the target resource from the diagnostic's related information + const targetUri = fromVsCodeUri( + diagnostic.relatedInformation[0].location.uri + ); + const targetResource = workspace.get(targetUri); + // Look up the section in the target resource by matching either heading ID or block ID. + // The sectionId may be a heading's s.id or a block's s.blockId (including caret notation). + const section = targetResource.sections.find( + s => s.id === sectionId || s.blockId === sectionId + ); + + if (!section) { + return null; // Should not happen if IDs are correctly passed + } + + const getTitle = () => { + switch (section.type) { + case 'heading': + return `Use heading "${section.label}"`; + case 'block': + return `Use block "${section.blockId}"`; + } + }; + + const getReplacementValue = () => { + switch (section.type) { + case 'heading': + return section.id; + case 'block': + return section.blockId; // Do not remove the '^' for insertion + } + }; + const action = new vscode.CodeAction( - `${section}`, + getTitle(), vscode.CodeActionKind.QuickFix ); action.command = { command: REPLACE_TEXT_COMMAND.name, - title: `Use section "${section}"`, + title: getTitle(), arguments: [ { - value: section, + value: getReplacementValue(), range: new vscode.Range( diagnostic.range.start.line, diagnostic.range.start.character + 1, @@ -262,6 +423,15 @@ const createReplaceSectionCommand = ( return action; }; +/** + * Creates a Code Action to fix an ambiguous link by replacing the link text + * with an unambiguous identifier for the chosen file. + * @param diagnostic The `AMBIGUOUS_IDENTIFIER_CODE` diagnostic. + * @param target The URI of the specific file the user wants to link to. + * @param defaultExtension The workspace's default file extension. + * @param possibleTargets The list of all possible target URIs. + * @returns A `vscode.CodeAction`. + */ const createFindIdentifierCommand = ( diagnostic: vscode.Diagnostic, target: vscode.Uri, diff --git a/packages/foam-vscode/src/services/editor.ts b/packages/foam-vscode/src/services/editor.ts index 6269b2e7b..2a88f5353 100644 --- a/packages/foam-vscode/src/services/editor.ts +++ b/packages/foam-vscode/src/services/editor.ts @@ -37,9 +37,9 @@ interface SelectionInfo { * Returns a MarkdownString of the note content * @param note A Foam Note */ -export function getNoteTooltip(content: string): string { +export function getNoteTooltip(content: string): MarkdownString { const strippedContent = stripFrontMatter(stripImages(content)); - return formatMarkdownTooltip(strippedContent) as any; + return formatMarkdownTooltip(strippedContent); } export function formatMarkdownTooltip(content: string): MarkdownString { @@ -188,7 +188,7 @@ export async function readFile(uri: URI): Promise { if (await fileExists(uri)) { return workspace.fs .readFile(toVsCodeUri(uri)) - .then(bytes => bytes.toString()); + .then(bytes => new TextDecoder('utf-8').decode(bytes)); } return undefined; } @@ -200,16 +200,21 @@ export function deleteFile(uri: URI) { /** * Turns a relative URI into an absolute URI for the given workspace. * @param uriOrPath the uri or path to evaluate + * @param forceSubfolder if true, if the URI is absolute and not a subfolder in the workspace, + * it will be forced to be a subfolder of the first workspace folder * @returns an absolute uri */ -export function asAbsoluteWorkspaceUri(uriOrPath: URI | string): URI { +export function asAbsoluteWorkspaceUri( + uriOrPath: URI | string, + forceSubfolder = false +): URI { if (workspace.workspaceFolders === undefined) { throw new Error('An open folder or workspace is required'); } const folders = workspace.workspaceFolders.map(folder => fromVsCodeUri(folder.uri) ); - const res = asAbsoluteUri(uriOrPath, folders); + const res = asAbsoluteUri(uriOrPath, folders, forceSubfolder); return res; } diff --git a/packages/foam-vscode/src/services/js-template-loader.ts b/packages/foam-vscode/src/services/js-template-loader.ts new file mode 100644 index 000000000..b76972018 --- /dev/null +++ b/packages/foam-vscode/src/services/js-template-loader.ts @@ -0,0 +1,206 @@ +import * as vm from 'vm'; +import { readFile } from './editor'; +import { URI } from '../core/model/uri'; +import { CreateNoteFunction, TemplateContext } from './note-creation-types'; +import { createTemplateSandbox, BLOCKED_GLOBALS } from './js-template-sandbox'; +import { Logger } from '../core/utils/log'; + +/** + * Error thrown when there are issues loading or executing JavaScript templates + */ +export class JSTemplateError extends Error { + constructor(message: string, public readonly templatePath: string) { + super(`JavaScript template error in ${templatePath}: ${message}`); + this.name = 'JSTemplateError'; + } +} + +/** + * Loader for JavaScript template functions with secure VM execution + */ +export class JSTemplateLoader { + private static readonly EXECUTION_TIMEOUT = 10000; // 10 seconds + private static readonly VM_OPTIONS: vm.RunningScriptOptions = { + timeout: JSTemplateLoader.EXECUTION_TIMEOUT, + displayErrors: true, + }; + + /** + * Loads and returns a note creation function from a JavaScript template file + * + * @param template Path to the JavaScript template file + * @returns The createNote function from the template + */ + async loadFunction(template: URI): Promise { + try { + Logger.info(`Loading JavaScript template: ${template.path}`); + + const templateCode = await readFile(template); + + if (!templateCode) { + throw new JSTemplateError( + `Template file not found or empty`, + template.path + ); + } + + return this.createFunctionFromCode(templateCode, template); + } catch (error) { + if (error instanceof JSTemplateError) { + throw error; + } + throw new JSTemplateError( + `Failed to load template: ${error.message}`, + template.path + ); + } + } + + /** + * Creates a note creation function from JavaScript code + * + * @param code The JavaScript code containing the createNote function + * @param template Path for error reporting + * @returns The createNote function + */ + private createFunctionFromCode( + code: string, + template: URI + ): CreateNoteFunction { + try { + // Validate the code structure + this.validateTemplateCode(code, template); + + // Create the VM context with sandbox + const sandbox = this.createVMSandbox(); + const context = vm.createContext(sandbox); + + // Execute the template code in the sandbox + const script = new vm.Script(code, { + filename: template.toFsPath(), + lineOffset: 0, + columnOffset: 0, + }); + + script.runInContext(context, JSTemplateLoader.VM_OPTIONS); + + // Extract the createNote function + const createNote = context.createNote; + if (typeof createNote !== 'function') { + throw new JSTemplateError( + 'Template must declare a createNote function', + template.path + ); + } + + // Wrap the function to inject the sandbox context + return async (noteContext: TemplateContext) => { + try { + // Update the sandbox with the current context + const contextSandbox = createTemplateSandbox(noteContext); + Object.assign(context, contextSandbox); + + // Execute the template function + const result = await createNote(noteContext); + + // Validate the result + this.validateResult(result, template); + + return result; + } catch (error) { + if (error instanceof JSTemplateError) { + throw error; + } + throw new JSTemplateError( + `Template execution failed: ${error.message}`, + template.path + ); + } + }; + } catch (error) { + if (error instanceof JSTemplateError) { + throw error; + } + throw new JSTemplateError( + `Failed to create function: ${error.message}`, + template.path + ); + } + } + + /** + * Creates a secure VM sandbox with limited globals + */ + private createVMSandbox() { + const sandbox: Record = {}; + + // Block dangerous globals + BLOCKED_GLOBALS.forEach(globalName => { + sandbox[globalName] = undefined; + }); + + return sandbox; + } + + /** + * Validates that the template code has the expected structure + */ + private validateTemplateCode(code: string, template: URI): void { + // Check for createNote function + if ( + !code.includes('function createNote') && + !code.includes('createNote =') + ) { + throw new JSTemplateError( + 'Template must define a createNote function', + template.path + ); + } + + // Check for potentially dangerous patterns + const dangerousPatterns = [ + /require\s*\(/, + /import\s+/, + /eval\s*\(/, + /Function\s*\(/, + /process\./, + /__dirname/, + /__filename/, + ]; + + for (const pattern of dangerousPatterns) { + if (pattern.test(code)) { + throw new JSTemplateError( + `Template contains potentially unsafe code: ${pattern.source}`, + template.path + ); + } + } + } + + /** + * Validates the result returned by a template function + */ + private validateResult(result: any, template: URI): void { + if (!result || typeof result !== 'object') { + throw new JSTemplateError( + 'Template must return an object with filepath and content properties', + template.path + ); + } + + if (typeof result.filepath !== 'string' || !result.filepath.trim()) { + throw new JSTemplateError( + 'Template result must have a non-empty filepath string', + template.path + ); + } + + if (typeof result.content !== 'string') { + throw new JSTemplateError( + 'Template result must have a content string', + template.path + ); + } + } +} diff --git a/packages/foam-vscode/src/services/js-template-sandbox.ts b/packages/foam-vscode/src/services/js-template-sandbox.ts new file mode 100644 index 000000000..1206e1740 --- /dev/null +++ b/packages/foam-vscode/src/services/js-template-sandbox.ts @@ -0,0 +1,63 @@ +import { TemplateContext } from './note-creation-types'; +import { URI } from '../core/model/uri'; +import { toSlug } from '../utils/slug'; +import { Logger } from '../core/utils/log'; +import dayjs from 'dayjs'; + +/** + * Creates a sandbox environment for JavaScript template execution + * This provides utility functions and safe globals for template functions + */ +export function createTemplateSandbox(context: TemplateContext) { + return { + // Common JavaScript globals (safe subset) + Date, + Math, + Object, + Array, + String, + Number, + Boolean, + JSON, + RegExp, + Error, + + // Console for debugging (logs to Foam output channel) + console: { + log: (...args: any[]) => + Logger.info(`[Template] ${args[0]}`, ...args.slice(1)), + warn: (...args: any[]) => + Logger.warn(`[Template] ${args[0]}`, ...args.slice(1)), + error: (...args: any[]) => + Logger.error(`[Template] ${args[0]}`, ...args.slice(1)), + }, + + // Utility functions + dayjs, + slugify: toSlug, + URI, + }; +} + +/** + * List of globals that should NOT be available in the template sandbox + * for security reasons + */ +export const BLOCKED_GLOBALS = [ + 'require', + 'module', + 'exports', + '__dirname', + '__filename', + 'global', + 'process', + 'Buffer', + 'setImmediate', + 'clearImmediate', + 'setInterval', + 'clearInterval', + 'setTimeout', + 'clearTimeout', + 'eval', + 'Function', +]; diff --git a/packages/foam-vscode/src/services/note-creation-engine.test.ts b/packages/foam-vscode/src/services/note-creation-engine.test.ts new file mode 100644 index 000000000..1ad64bd85 --- /dev/null +++ b/packages/foam-vscode/src/services/note-creation-engine.test.ts @@ -0,0 +1,473 @@ +import { tmpdir } from 'os'; +import { mkdtempSync } from 'fs'; +import { NoteCreationEngine } from './note-creation-engine'; +import { TriggerFactory } from './note-creation-triggers'; +import { + Template, + isCommandTrigger, + isPlaceholderTrigger, +} from './note-creation-types'; +import { readFileFromFs, strToUri } from '../test/test-utils'; +import { bootstrap } from '../core/model/foam'; +import { FileDataStore, Matcher } from '../test/test-datastore'; +import { MarkdownResourceProvider } from '../core/services/markdown-provider'; +import { createMarkdownParser } from '../core/services/markdown-parser'; +import { Logger } from '../core/utils/log'; +import { Resolver } from './variable-resolver'; +import { URI } from '../core/model/uri'; + +Logger.setLevel('off'); + +async function setupFoamEngine() { + // Set up Foam workspace (minimal setup for testing) + const tmpDir = mkdtempSync(`${tmpdir()}/foam-test-`); + const dataStore = new FileDataStore(readFileFromFs, tmpDir); + const matcher = new Matcher([strToUri(tmpDir)], ['**/*.md']); + const parser = createMarkdownParser(); + const provider = new MarkdownResourceProvider(dataStore, parser, ['.md']); + const foam = await bootstrap(matcher, undefined, dataStore, parser, [ + provider, + ]); + const engine = new NoteCreationEngine(foam, [strToUri(tmpDir)]); + return { foam, engine }; +} + +describe('NoteCreationEngine', () => { + describe('processTemplate', () => { + it('should process markdown templates correctly', async () => { + const { engine } = await setupFoamEngine(); + // Create markdown template + const template: Template = { + type: 'markdown', + content: `--- +filepath: test-note.md +--- +# \${FOAM_TITLE} + +Test content with title: \${FOAM_TITLE}`, + metadata: new Map([['filepath', 'test-note.md']]), + }; + + // Create trigger + const trigger = TriggerFactory.createCommandTrigger( + 'foam-vscode.create-note' + ); + + // Create resolver with variables + const resolver = new Resolver(new Map(), new Date()); + resolver.define('FOAM_TITLE', 'Test Note'); + + // Test processing + const result = await engine.processTemplate(trigger, template, resolver); + + expect(result.filepath.path).toBe('test-note.md'); + expect(result.content).toContain('# Test Note'); + expect(result.content).toContain('Test content with title: Test Note'); + }); + + it('should handle command triggers with date parameters', async () => { + const { engine } = await setupFoamEngine(); + // Create markdown template with date variables + const template: Template = { + type: 'markdown', + content: `# Daily Note \${FOAM_DATE_YEAR}-\${FOAM_DATE_MONTH}-\${FOAM_DATE_DATE} + +Today is \${FOAM_DATE_DAY_NAME}`, + }; + + // Create context with date trigger + const testDate = new Date('2024-01-15'); + const trigger = TriggerFactory.createCommandTrigger( + 'foam-vscode.open-daily-note', + { + date: testDate, + } + ); + + // Create resolver with date variables + const resolver = new Resolver(new Map(), testDate); + resolver.define('FOAM_TITLE', '2024-01-15'); + resolver.define('FOAM_DATE_YEAR', '2024'); + resolver.define('FOAM_DATE_MONTH', '01'); + resolver.define('FOAM_DATE_DATE', '15'); + resolver.define('FOAM_DATE_DAY_NAME', 'Monday'); + + // Test processing with date variables + const result = await engine.processTemplate(trigger, template, resolver); + + expect(result.content).toContain('Daily Note 2024-01-15'); + expect(result.content).toContain('Today is Monday'); + + // Verify trigger type handling + expect(trigger.type).toBe('command'); + if (!isCommandTrigger(trigger)) { + throw new Error('Expected command trigger type'); + } + expect(trigger.command).toBe('foam-vscode.open-daily-note'); + expect(trigger.params).toHaveProperty('date'); + }); + + it('should handle placeholder triggers correctly', async () => { + const { engine } = await setupFoamEngine(); + // Create markdown template + const template: Template = { + type: 'markdown', + content: `# \${FOAM_TITLE} + +Created from placeholder link. + +Content goes here.`, + }; + + // Create placeholder trigger + const trigger = TriggerFactory.createPlaceholderTrigger( + strToUri('/test/source.md'), + 'Source Note', + { + uri: strToUri('/test/source.md'), + range: { + start: { line: 0, character: 0 }, + end: { line: 0, character: 10 }, + }, + data: { rawText: '[[Test Note]]' }, + } as any + ); + + // Create resolver with variables + const resolver = new Resolver(new Map(), new Date()); + resolver.define('FOAM_TITLE', 'Test Note'); + + // Test processing + const result = await engine.processTemplate(trigger, template, resolver); + + expect(result.content).toContain('# Test Note'); + expect(result.content).toContain('Created from placeholder link'); + + // Verify trigger type handling + expect(trigger.type).toBe('placeholder'); + if (!isPlaceholderTrigger(trigger)) { + throw new Error('Expected placeholder trigger type'); + } + expect(trigger.sourceNote.title).toBe('Source Note'); + expect(trigger.sourceNote.uri).toBe( + strToUri('/test/source.md').toString() + ); + }); + + it('should generate default filepath when not specified in template', async () => { + const { engine } = await setupFoamEngine(); + // Create markdown template without filepath metadata + const template: Template = { + type: 'markdown', + content: `# \${FOAM_TITLE} + +Content without filepath metadata.`, + }; + + // Create resolver with variables + const resolver = new Resolver(new Map(), new Date()); + resolver.define('FOAM_TITLE', 'My New Note'); + resolver.define('title', 'My New Note'); + + // Test processing + const result = await engine.processTemplate( + TriggerFactory.createCommandTrigger('foam-vscode.create-note'), + template, + resolver + ); + + expect(result.content).toContain('# My New Note'); + expect(result.filepath.path).toBe('My New Note.md'); // Should generate from title + }); + + it('should handle JavaScript templates correctly', async () => { + const { engine } = await setupFoamEngine(); + // Create JavaScript template + const template: Template = { + type: 'javascript', + createNote: async context => { + const title = + (await context.resolver.resolveFromName('FOAM_TITLE')) || + 'Untitled'; + const content = `# ${title}\n\nGenerated by JavaScript template\n\nTrigger: ${context.trigger.type}`; + return { + filepath: URI.parse( + `${title.replace(/\s+/g, '-').toLowerCase()}.md` + ), + content, + }; + }, + }; + + // Create resolver with variables + const resolver = new Resolver(new Map(), new Date()); + resolver.define('FOAM_TITLE', 'JS Generated Note'); + resolver.define('title', 'JS Generated Note'); + + // Test processing + const result = await engine.processTemplate( + TriggerFactory.createCommandTrigger('foam-vscode.create-note'), + template, + resolver + ); + + expect(result.content).toContain('# JS Generated Note'); + expect(result.content).toContain('Generated by JavaScript template'); + expect(result.content).toContain('Trigger: command'); + expect(result.filepath.path).toBe('js-generated-note.md'); + }); + }); + + describe('JavaScript template error handling', () => { + it('should handle synchronous errors thrown by JavaScript templates', async () => { + const { engine } = await setupFoamEngine(); + + // Create JavaScript template that throws synchronously + const template: Template = { + type: 'javascript', + createNote: () => { + throw new Error('Template execution failed'); + }, + }; + + const resolver = new Resolver(new Map(), new Date()); + const trigger = TriggerFactory.createCommandTrigger( + 'foam-vscode.create-note' + ); + + // Test that error is properly caught and handled + await expect( + engine.processTemplate(trigger, template, resolver) + ).rejects.toThrow('Template execution failed'); + }); + + it('should handle asynchronous errors thrown by JavaScript templates', async () => { + const { engine } = await setupFoamEngine(); + + // Create JavaScript template that throws asynchronously + const template: Template = { + type: 'javascript', + createNote: async () => { + await new Promise(resolve => setTimeout(resolve, 10)); + throw new Error('Async template execution failed'); + }, + }; + + const resolver = new Resolver(new Map(), new Date()); + const trigger = TriggerFactory.createCommandTrigger( + 'foam-vscode.create-note' + ); + + // Test that async error is properly caught and handled + await expect( + engine.processTemplate(trigger, template, resolver) + ).rejects.toThrow('Async template execution failed'); + }); + + it('should handle JavaScript templates returning null/undefined', async () => { + const { engine } = await setupFoamEngine(); + + // Create JavaScript template that returns null + const nullTemplate: Template = { + type: 'javascript', + createNote: () => null as any, + }; + + const resolver = new Resolver(new Map(), new Date()); + const trigger = TriggerFactory.createCommandTrigger( + 'foam-vscode.create-note' + ); + + // Test that null return is handled + await expect( + engine.processTemplate(trigger, nullTemplate, resolver) + ).rejects.toThrow(); + + // Create JavaScript template that returns undefined + const undefinedTemplate: Template = { + type: 'javascript', + createNote: () => undefined as any, + }; + + // Test that undefined return is handled + await expect( + engine.processTemplate(trigger, undefinedTemplate, resolver) + ).rejects.toThrow(); + }); + + it('should handle JavaScript templates returning invalid data structures', async () => { + const { engine } = await setupFoamEngine(); + + // Create JavaScript template that returns object with missing filepath + const missingFilepathTemplate: Template = { + type: 'javascript', + createNote: () => + ({ + content: 'Valid content', + // Missing filepath + } as any), + }; + + const resolver = new Resolver(new Map(), new Date()); + const trigger = TriggerFactory.createCommandTrigger( + 'foam-vscode.create-note' + ); + + // Test that missing filepath is handled + await expect( + engine.processTemplate(trigger, missingFilepathTemplate, resolver) + ).rejects.toThrow(); + + // Create JavaScript template that returns object with missing content + const missingContentTemplate: Template = { + type: 'javascript', + createNote: () => + ({ + filepath: 'valid-path.md', + // Missing content + } as any), + }; + + // Test that missing content is handled + await expect( + engine.processTemplate(trigger, missingContentTemplate, resolver) + ).rejects.toThrow(); + + // Create JavaScript template that returns wrong data types + const wrongTypesTemplate: Template = { + type: 'javascript', + createNote: () => + ({ + filepath: 123, // Should be string + content: true, // Should be string + } as any), + }; + + // Test that wrong data types are handled + await expect( + engine.processTemplate(trigger, wrongTypesTemplate, resolver) + ).rejects.toThrow(); + }); + + it('should handle JavaScript templates with rejected promises', async () => { + const { engine } = await setupFoamEngine(); + + // Create JavaScript template that returns rejected promise + const rejectedPromiseTemplate: Template = { + type: 'javascript', + createNote: () => Promise.reject(new Error('Promise rejected')), + }; + + const resolver = new Resolver(new Map(), new Date()); + const trigger = TriggerFactory.createCommandTrigger( + 'foam-vscode.create-note' + ); + + // Test that rejected promise is handled + await expect( + engine.processTemplate(trigger, rejectedPromiseTemplate, resolver) + ).rejects.toThrow('Promise rejected'); + }); + + it('should handle JavaScript templates with mixed sync/async errors', async () => { + const { engine } = await setupFoamEngine(); + + // Create JavaScript template that sometimes throws sync, sometimes async + let callCount = 0; + const mixedErrorTemplate: Template = { + type: 'javascript', + createNote: () => { + callCount++; + if (callCount % 2 === 0) { + throw new Error('Sync error'); + } else { + return Promise.reject(new Error('Async error')); + } + }, + }; + + const resolver = new Resolver(new Map(), new Date()); + const trigger = TriggerFactory.createCommandTrigger( + 'foam-vscode.create-note' + ); + + // Test first call (async error) + await expect( + engine.processTemplate(trigger, mixedErrorTemplate, resolver) + ).rejects.toThrow('Async error'); + + // Test second call (sync error) + await expect( + engine.processTemplate(trigger, mixedErrorTemplate, resolver) + ).rejects.toThrow('Sync error'); + }); + + it('should handle JavaScript templates that return promises resolving to invalid data', async () => { + const { engine } = await setupFoamEngine(); + + // Create JavaScript template that returns promise resolving to invalid data + const invalidPromiseTemplate: Template = { + type: 'javascript', + createNote: () => + Promise.resolve({ + filepath: null, + content: null, + } as any), + }; + + const resolver = new Resolver(new Map(), new Date()); + const trigger = TriggerFactory.createCommandTrigger( + 'foam-vscode.create-note' + ); + + // Test that invalid promise resolution is handled + await expect( + engine.processTemplate(trigger, invalidPromiseTemplate, resolver) + ).rejects.toThrow(); + }); + }); + + describe('trigger validation', () => { + it('should validate command triggers', () => { + const trigger = TriggerFactory.createCommandTrigger( + 'foam-vscode.open-daily-note', + { date: new Date() } + ); + + expect(trigger.type).toBe('command'); + if (!isCommandTrigger(trigger)) { + throw new Error('Expected command trigger type'); + } + expect(trigger.command).toBe('foam-vscode.open-daily-note'); + expect(trigger.params).toHaveProperty('date'); + }); + + it('should validate placeholder triggers', () => { + const sourceUri = strToUri('/test/source.md'); + const mockLocation = { + uri: sourceUri, + range: { + start: { line: 0, character: 0 }, + end: { line: 0, character: 10 }, + }, + data: { rawText: '[[Test Note]]' }, + } as any; + + const trigger = TriggerFactory.createPlaceholderTrigger( + sourceUri, + 'Source Note', + mockLocation + ); + + expect(trigger.type).toBe('placeholder'); + if (!isPlaceholderTrigger(trigger)) { + throw new Error('Expected placeholder trigger type'); + } + expect(trigger.sourceNote).toMatchObject({ + uri: sourceUri.toString(), + title: 'Source Note', + location: mockLocation, + }); + }); + }); +}); diff --git a/packages/foam-vscode/src/services/note-creation-engine.ts b/packages/foam-vscode/src/services/note-creation-engine.ts new file mode 100644 index 000000000..9ac4c7ff8 --- /dev/null +++ b/packages/foam-vscode/src/services/note-creation-engine.ts @@ -0,0 +1,197 @@ +import { Resolver } from './variable-resolver'; +import { Foam } from '../core/model/foam'; +import { Logger } from '../core/utils/log'; +import { + NoteCreationResult, + NoteCreationTrigger, + Template, + TemplateContext, + isCommandTrigger, + isPlaceholderTrigger, +} from './note-creation-types'; +import { extractFoamTemplateFrontmatterMetadata } from '../utils/template-frontmatter-parser'; +import { asAbsoluteUri, URI } from '../core/model/uri'; +import { isAbsolute } from 'path'; + +/** + * Unified engine for creating notes from both Markdown and JavaScript templates + */ +export class NoteCreationEngine { + constructor(private foam: Foam, private roots: URI[]) {} + + /** + * Processes a template and generates note content and filepath + * This method only handles template processing, not file creation + * + * @param trigger The trigger that initiated the note creation + * @param template The template object containing content or function + * @param resolver Resolver instance with all variables pre-configured + * @returns Promise resolving to the generated content and filepath + */ + async processTemplate( + trigger: NoteCreationTrigger, + template: Template, + resolver: Resolver + ): Promise { + Logger.info(`Processing ${template.type} template`); + this.logTriggerInfo(trigger); + + let result: NoteCreationResult | null = null; + if (template.type === 'javascript') { + result = await this.executeJSTemplate(trigger, template, resolver); + } else { + result = await this.executeMarkdownTemplate(trigger, template, resolver); + } + + return { + ...result, + filepath: result.filepath, + }; + } + + /** + * Executes a JavaScript template + */ + private async executeJSTemplate( + trigger: NoteCreationTrigger, + template: Template & { type: 'javascript' }, + resolver: Resolver + ): Promise { + // Convert resolver's variables back to extraParams for backward compatibility + const extraParams = resolver.getVariables(); + + const templateContext: TemplateContext = { + trigger, + resolver, + foam: this.foam, + foamDate: resolver.foamDate, + }; + + try { + const result = await template.createNote(templateContext); + + // Validate the result structure and types + this.validateNoteCreationResult(result); + + if (!(result.filepath instanceof URI)) { + result.filepath = URI.parse(result.filepath); + } + return result; + } catch (error) { + const errorMessage = + error instanceof Error ? error.message : String(error); + Logger.error(`JavaScript template execution failed: ${errorMessage}`); + throw new Error(`JavaScript template execution failed: ${errorMessage}`); + } + } + + /** + * Executes a Markdown template using variable resolution + */ + private async executeMarkdownTemplate( + trigger: NoteCreationTrigger, + template: Template & { type: 'markdown' }, + resolver: Resolver + ): Promise { + // Use the provided resolver directly for variable resolution + const resolvedContent = await resolver.resolveText(template.content); + + // Process frontmatter metadata + const [frontmatterMetadata, cleanContent] = + extractFoamTemplateFrontmatterMetadata(resolvedContent); + + // Combine template metadata with frontmatter metadata (frontmatter takes precedence) + const metadata = new Map([ + ...(template.metadata ?? new Map()), + ...frontmatterMetadata, + ]); + + // Determine filepath - get variables from resolver for default generation + const filepath = + metadata.get('filepath') ?? + (await this.generateDefaultFilepath(resolver)); + + return { + filepath: URI.parse(filepath), + content: cleanContent, + }; + } + + /** + * Generates a default filepath when none is specified in the template + */ + private async generateDefaultFilepath(resolver: Resolver): Promise { + const name = + (await resolver.resolveFromName('FOAM_TITLE_SAFE')) || 'untitled'; + return `${name}.md`; + } + + /** + * Validates the result returned by a JavaScript template + */ + private validateNoteCreationResult( + result: any + ): asserts result is NoteCreationResult { + if (!result || typeof result !== 'object') { + throw new Error('JavaScript template must return an object'); + } + + if ( + !Object.prototype.hasOwnProperty.call(result, 'filepath') || + (typeof result.filepath !== 'string' && !(result.filepath instanceof URI)) + ) { + throw new Error( + 'JavaScript template result must have a "filepath" property of type string or URI' + ); + } + + if ( + !Object.prototype.hasOwnProperty.call(result, 'content') || + typeof result.content !== 'string' + ) { + throw new Error( + 'JavaScript template result must have a "content" property of type string' + ); + } + + // Optional: Validate filepath doesn't contain dangerous characters + const invalidChars = /[<>:"|?*\x00-\x1F]/; // eslint-disable-line no-control-regex + if (invalidChars.test(result.filepath.path)) { + throw new Error( + 'JavaScript template result "filepath" contains invalid characters' + ); + } + } + + /** + * Logs trigger-specific information for debugging + */ + private logTriggerInfo(trigger: NoteCreationTrigger): void { + if (isCommandTrigger(trigger)) { + Logger.info(`Note creation triggered by command: ${trigger.command}`); + if (trigger.params) { + Logger.info(`Command params:`, trigger.params); + } + + // Handle specific commands + switch (trigger.command) { + case 'foam-vscode.open-daily-note': { + const date = trigger.params?.date; + Logger.info(`Daily note for date: ${date}`); + break; + } + case 'foam-vscode.create-note-from-template': { + const templateUri = trigger.params?.templateUri; + Logger.info(`Using template: ${templateUri}`); + break; + } + default: + Logger.info(`Generic command: ${trigger.command}`); + } + } else if (isPlaceholderTrigger(trigger)) { + const sourceNote = trigger.sourceNote; + Logger.info(`Creating note from placeholder in: ${sourceNote.title}`); + Logger.info(`Source URI: ${sourceNote.uri}`); + } + } +} diff --git a/packages/foam-vscode/src/services/note-creation-triggers.ts b/packages/foam-vscode/src/services/note-creation-triggers.ts new file mode 100644 index 000000000..d597a44ef --- /dev/null +++ b/packages/foam-vscode/src/services/note-creation-triggers.ts @@ -0,0 +1,46 @@ +import { URI } from '../core/model/uri'; +import { Location } from '../core/model/location'; +import { ResourceLink } from '../core/model/note'; +import { NoteCreationTrigger } from './note-creation-types'; + +/** + * Factory class for creating different types of note creation triggers + */ +export class TriggerFactory { + /** + * Creates a command trigger for note creation initiated by VS Code commands + * + * @param command The command name that triggered note creation + * @param params Optional parameters associated with the command + * @returns A command trigger object + */ + static createCommandTrigger( + command: string, + params?: Record + ): NoteCreationTrigger { + return { type: 'command', command, params }; + } + + /** + * Creates a placeholder trigger for note creation from wikilink placeholders + * + * @param sourceUri URI of the source note containing the placeholder + * @param sourceTitle Title of the source note + * @param location Location information for the placeholder in the source note + * @returns A placeholder trigger object + */ + static createPlaceholderTrigger( + sourceUri: URI, + sourceTitle: string, + location: Location + ): NoteCreationTrigger { + return { + type: 'placeholder', + sourceNote: { + uri: sourceUri.toString(), + title: sourceTitle, + location, + }, + }; + } +} diff --git a/packages/foam-vscode/src/services/note-creation-types.ts b/packages/foam-vscode/src/services/note-creation-types.ts new file mode 100644 index 000000000..090363844 --- /dev/null +++ b/packages/foam-vscode/src/services/note-creation-types.ts @@ -0,0 +1,84 @@ +import { Location } from '../core/model/location'; +import { ResourceLink } from '../core/model/note'; +import { Foam } from '../core/model/foam'; +import { Resolver } from './variable-resolver'; +import { URI } from '../core/model/uri'; + +/** + * Union type for different trigger scenarios that can initiate note creation + */ +export type NoteCreationTrigger = + | { + type: 'command'; + command: string; + params?: Record; // Command arguments/parameters + } + | { + type: 'placeholder'; + sourceNote: { + uri: string; + title: string; + location: Location; + }; + }; + +/** + * Template types supported by the note creation system + */ +export type Template = + | { type: 'markdown'; content: string; metadata?: Map } + | { + type: 'javascript'; + createNote: (context: TemplateContext) => Promise; + }; + +/** + * Context provided to JavaScript template functions + */ +export interface TemplateContext { + /** The trigger that initiated the note creation */ + trigger: NoteCreationTrigger; + /** Resolver instance for variable resolution */ + resolver: Resolver; + /** Foam instance for accessing workspace data */ + foam: Foam; + /** Date used by the resolver for the FOAM_DATE_* variables */ + foamDate: Date; +} + +/** + * Context for creating a note through the unified creation system + */ + +/** + * Result returned by note creation functions + */ +export interface NoteCreationResult { + filepath: URI; + content: string; +} + +/** + * Function signature for JavaScript template functions + */ +export type CreateNoteFunction = ( + context: TemplateContext +) => Promise | NoteCreationResult; + +/** + * Type guard to check if trigger is a command trigger + */ +export function isCommandTrigger( + trigger: NoteCreationTrigger +): trigger is NoteCreationTrigger & { type: 'command' } { + return trigger.type === 'command'; +} + +/** + * Type guard to check if trigger is a placeholder trigger + */ +export function isPlaceholderTrigger( + trigger: NoteCreationTrigger +): trigger is NoteCreationTrigger & { type: 'placeholder' } { + return trigger.type === 'placeholder'; +} diff --git a/packages/foam-vscode/src/services/template-loader.spec.ts b/packages/foam-vscode/src/services/template-loader.spec.ts new file mode 100644 index 000000000..e7c451b1c --- /dev/null +++ b/packages/foam-vscode/src/services/template-loader.spec.ts @@ -0,0 +1,86 @@ +/* @unit-ready */ +import { workspace } from 'vscode'; +import { TemplateLoader } from './template-loader'; +import { createFile, deleteFile } from '../test/test-utils-vscode'; +import { randomString } from '../test/test-utils'; + +describe('TemplateLoader', () => { + describe('workspace trust', () => { + it('should throw error when loading JS template in untrusted workspace', async () => { + const templateLoader = new TemplateLoader(); + const mockIsTrusted = jest.spyOn(workspace, 'isTrusted', 'get'); + mockIsTrusted.mockReturnValue(false); + + const { uri } = await createFile( + 'function createNote() { return { filepath: "test.md", content: "test" }; }', + [`test-template-${randomString()}.js`] + ); + + try { + await expect(templateLoader.loadTemplate(uri)).rejects.toThrow( + 'JavaScript templates can only be used in trusted workspaces for security reasons' + ); + } finally { + await deleteFile(uri); + mockIsTrusted.mockRestore(); + } + }); + + it('should load JS template successfully in trusted workspace', async () => { + const templateLoader = new TemplateLoader(); + const mockIsTrusted = jest.spyOn(workspace, 'isTrusted', 'get'); + mockIsTrusted.mockReturnValue(true); + + const jsTemplateContent = ` + function createNote(context) { + return { + filepath: 'test-note.md', + content: '# Test Note\\n\\nGenerated by JS template' + }; + } + `; + const { uri } = await createFile(jsTemplateContent, [ + `test-template-${randomString()}.js`, + ]); + + try { + const template = await templateLoader.loadTemplate(uri); + expect(template.type).toBe('javascript'); + if (template.type !== 'javascript') { + throw new Error('Expected JavaScript template type'); + } + expect(template.createNote).toBeDefined(); + expect(typeof template.createNote).toBe('function'); + } finally { + await deleteFile(uri); + } + }); + + it('should load markdown template regardless of workspace trust', async () => { + const templateLoader = new TemplateLoader(); + const mockIsTrusted = jest.spyOn(workspace, 'isTrusted', 'get'); + mockIsTrusted.mockReturnValue(false); + + const mdTemplateContent = `--- +name: Test Template +--- +# Test Note + +This is a markdown template.`; + const { uri } = await createFile(mdTemplateContent, [ + `test-template-${randomString()}.md`, + ]); + + try { + const template = await templateLoader.loadTemplate(uri); + expect(template.type).toBe('markdown'); + if (template.type !== 'markdown') { + throw new Error('Expected markdown template type'); + } + expect(template.content).toBe(mdTemplateContent); + } finally { + await deleteFile(uri); + } + }); + }); +}); diff --git a/packages/foam-vscode/src/services/template-loader.ts b/packages/foam-vscode/src/services/template-loader.ts new file mode 100644 index 000000000..dd6a3d95e --- /dev/null +++ b/packages/foam-vscode/src/services/template-loader.ts @@ -0,0 +1,77 @@ +import { workspace } from 'vscode'; +import { URI } from '../core/model/uri'; +import { readFile } from './editor'; +import { + Template, + TemplateContext, + NoteCreationResult, +} from './note-creation-types'; +import { extractFoamTemplateFrontmatterMetadata } from '../utils/template-frontmatter-parser'; +import { JSTemplateLoader } from './js-template-loader'; + +/** + * Utility for loading templates from file paths and converting them to Template objects + */ +export class TemplateLoader { + private jsTemplateLoader: JSTemplateLoader; + + constructor() { + this.jsTemplateLoader = new JSTemplateLoader(); + } + + /** + * Loads a template from a file path + * @param template Path to the template file (relative or absolute) + * @returns Promise resolving to a Template object + */ + async loadTemplate(template: URI): Promise