This is the source code repository for the libaacs-keydb VS Code extension.

This document is for contributors, not for users of this extension.
For user documentation, see: extension/README.md
For license information, see the bottom of this document.

For a list of features and details, see the user documentation: extension/README.md

Working on this VS Code extension requires the following programs to be installed on your system:

• yarn (required)
• nvm (recommended)

To prepare your session, cd to the project root directory, then run nvm use.

To install dependencies, run: yarn install

If that fails, consult the Maintenance section.

To build the extension, run: yarn package

Unlike vsce package, running yarn package will work around issue microsoft/vscode-vsce#517. Use yarn package as long as the issue is unresolved.

Publishing the extension has several steps:

1. Merge the contributions.
2. Choose a target version number.
3. Publish to the Marketplace. (This modifies extension/package.json.)
4. Publish to the Open VSX Registry.
5. Create a Git commit, Git tag, GitHub prerelease and GitHub PR.

Make sure that all the contributions you’re going to have in the release have been merged to the main branch.

With all contributions merged into main, choose a target version number.
The VS Code folks recommend the following numbering scheme:

• major.ODD_NUMBER.patch (e.g. 1.1.0) for pre-release versions; and
• major.EVEN_NUMBER.patch (e.g. 1.2.0) for release versions.

1. Check out the main branch and make sure it is pristine.

2. Decide on a new version number under which to publish the package.

3. Edit the extension/share/dist/package.json manifest to reflect the new version number.

4. Run: yarn package

5. If necessary, run: yarn workspace extension login

6. Run: yarn workspace extension publish-vsce [--pre-release]

The final yarn […] publish-vsce command packages and publishes the extension to the VS Code Extension Marketplace.

Follow these steps to publish the extension to the Open VSX Registry:

1. Set the OVSX_PAT environment variable to your personal access token.

   For example, if you’re on Bash and you have your token in 1Password, you could run the following command line:

   read -r OVSX_PAT < <(
     op item get 'Open VSX Registry' --fields password
   ) && export OVSX_PAT

2. Make sure you have published the extension to the VS Code Extension Marketplace. This ensures that the version number has been updated.

3. Run yarn package to generate a .vsix package.

4. Run the yarn […] ovsx publish command with the correct extension/dist/[…].vsix file as the sole argument.
   Example in Bash:

   yarn workspace extension ovsx publish "dist/libaacs-keydb-$(jq -r .version extension/share/dist/package.json).vsix"

With the extension now published on the Marketplace, commit the change, create a tag, push, cut a GitHub (pre-)release, and create a pull request against main:

(
  set -eux
  git checkout -b publish
  tag="$(jq -r '"v" + .version' extension/share/dist/package.json)"
  echo "New tag: ${tag}"
  git add -u
  git commit --edit -m "Release ${tag}"
  git tag "${tag}"
  git push --tags
  gh release create --draft --generate-notes --prerelease "${tag}"
  gh pr create --fill --web
)

To install the current project dependencies as specified in package.json and yarn.lock, run yarn install.

If the Yarn version has changed and you run yarn install, Yarn will try to upgrade itself. That causes changes to several files, such as the LICENSE files I have placed into several subdirectories.

Anytime that happens, run the yarn clean-install script, a wrapper around yarn install which cleans up afterwards.

Note that the yarn clean-install script may fail and tell you to run yarn install instead. I haven’t figured out why it does that. If that happens, run yarn install followed by yarn clean-install.

To see a list of outdated packages, run: yarn outdated

This runs yarn up -R '**' && yarn clean-install behind the scenes in order to upgrade all resolutions in the lockfile as far as possible, but leaves your package.json as is.

The built-in yarn up command can be a bit cumbersome to use if you want to upgrade all dependencies in one go.

Running the yarn upgrade-packages script will upgrade all relevant dependencies. That includes the @types, @typescript-eslint, and @yarnpkg scopes but excludes Yarn itself (see the yarn upgrade-yarn-itself section).

Also excluded is the @types/vscode package. For details, see section Upgrading the VS Code API version.

To upgrade Yarn PnP to the latest available version, run the yarn upgrade-yarn-itself script.

Note that the script will only print manual instructions. That’s because Yarn makes changes to package.json, and that doesn’t play well with Yarn PnP in scripts.

To also upgrade Yarn itself, run yarn upgrade-all.

Upgrading the version of the @types/vscode package should always be a manual step and a conscious decision. It effectively bumps the minimum supported VS Code version that this extension supports.

To bump the minimum supported VS Code version, follow these steps:

1. In package.json, manually update the minimum version to a new version tuple (e.g. =1.99).
   Make sure to preserve the = prefix as you change the value.

2. In package.json, modify the upgrade-package script to update the same tuple (e.g @types/vscode@=1.99).
   Preserve the @types/vscode@= prefix as you change the value.

3. In extension/package.json under the engines section, manually update the value of the vscode property to the chosen version. Since vsce expects a triple for that property, append a .0.
   Preserve the ^ prefix as you change the value.

4. Run yarn clean-install.

Sometimes you may want to tweak a dependency. This section explains how to do that using yarn patch.

To start editing a dependency, run yarn patch <dependency>.

For example, to start editing the vsce executable, run:

yarn patch @vscode/vsce@npm:2.21.1

Since this project is already patching this dependency, you may want to apply the existing patch to the temporary working directory:

patch < path/to/this/project/.yarn/patches/@vscode-vsce-npm-2.21.1.patch

To commit the patch, run yarn repatch -- <workdir>.

For example, if the temporary working directory is /tmp/xfs-36e26fe6/user, run:

yarn repatch -- /tmp/xfs-36e26fe6/user

Note: yarn repatch is a custom script. It serves to work around two issues in yarn patch-commit:

• Using bare yarn patch-commit would create a nested patch while amending the patch is what I actually want.

• It may also use an incorrect key in the resolution entry it writes to package.json.
  The key should match the dependency’s semver expression, not the resolved version. Using the latter as a key causes the resolution to never apply.
  Example for a correct key: "@vscode/vsce@^2.21.1"

People sometimes discover vulnerabilities in packages on which vscode-libaacs-keydb depends.

If that happens and a patch comes out, I need to upgrade the affected package to a newer version, which includes the patch.

But a vulnerability might also affect a package on which vscode-libaacs-keydb depends only indirectly, e.g. through a transitive requirement. A patch may exist for such a package, but somewhere in the chain of dependencies (from the vulnerable package all the way down to vscode-libaacs-keydb), the patch may be outside the specified semver range so I can’t upgrade the package via the usual yarn up or yarn up -R command.

If such cases arise, I’m going to try force-upgrading affected packages, and document those upgrades in the section List of force-upgraded transitive dependencies below.
Even if the upgrade happens to fail (or if it breaks the app and I have to roll back the upgrade, leaving the vulnerability unpatched), I’m also going to document that failure here.

The goal of this list is:

• to document the drift between version requirements (in the tree of package.json files) and the resolutions in yarn.lock; and

• to inform about unpatched vulnerabilities.

• libaacs key database file specification, format 1.0
• TextMate language grammars
• Default themes dark_vs and dark_plus as references on how VS Code renders grammar scopes.

This source code repository contains code and assets sourced from different parties. Therefore, multiple sets of license terms apply to different parts of this source code repository.

The following table shows which terms apply to which parts of this source code repository:

In each of the directories the table mentions, you will find one license file, named LICENSE or LICENSE.txt.
Each license file applies to the directory that contains it, including all subdirectories, but excluding any subdirectory tree whose root has a license file on its own.

Copyright (c) 2023 Claudia Pellegrino

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. For a copy of the License, see LICENSE.