<!-- markdownlint-disable -->
# Power Query libraries
This monorepo develops three TypeScript libraries for the Power Query / M language:
- [Parser](packages/powerquery-parser/README.md): lexing, parsing, ASTs, types, and shared utilities.
- [Formatter](packages/powerquery-formatter/README.md): formatting expressions and section documents.
- [Language services](packages/powerquery-language-services/README.md): IntelliSense, diagnostics,
navigation, renaming, symbols, and formatting for editors.
See each package's README for installation and API examples.
## Develop
From the repository root:
```powershell
npm ci --ignore-scripts
npm run clean
npm run build
npm run lint
npm test
npm run validate:release
```
There is one lockfile. Builds explicitly run parser, formatter, then services; no `npm link`,
per-package installs, or external source checkouts are needed. `npm test` includes all unit suites,
the parser resource suite, and release-helper tests. `npm run test:unit` and
`npm run test:parser:resources` are focused alternatives.
Shared development tools, including ESLint and Prettier, are declared in the private root manifest.
The exact Node.js version used for development and CI is pinned in `.node-version`; compatible
version managers can use that file automatically. When updating the development Node.js version,
update `.node-version` and the root `package.json` `engines.node` minimum together. The pin should
be bumped when adopting a newer Node.js LTS release or when a required runtime or toolchain update
needs a newer patch. Publishable packages declare their own consumer requirement. Runtime
dependencies remain in each publishable package so tarballs can be installed independently of the
workspace.
Common compiler settings live in `tsconfig.base.json`, with package-specific inputs and safety
options in each package's config. All packages use the same root ESLint rule set.
Compilation uses Node16 module resolution and preserves CommonJS output for the existing packages.
Mocha's shared config and composite reporter are configured once at the root;
package configs select their suites and the parser resource command selects its own XML output.
Use workspace commands after building prerequisites:
```powershell
npm test --workspace @microsoft/powerquery-formatter
npm run watch --workspace @microsoft/powerquery-language-services
npm run script:nodeDump --workspace @microsoft/powerquery-parser
npm run script:recursiveDirectoryFormat --workspace @microsoft/powerquery-formatter -- .\queries ".pq,.mout"
```
The last command overwrites formatted files; review the target directory first.
Relative script arguments resolve from the selected package directory; use absolute paths for
payloads or queries stored elsewhere.
Benchmark commands and methodology are documented in the
[formatter](packages/powerquery-formatter/README.md#benchmark) and
[services](packages/powerquery-language-services/README.md#benchmarking) READMEs.
Open the repository root in VS Code for package-aware build/debug tasks.
Production source is `packages/<name>/src`; tests and developer tools are package-root siblings.
Shared license, security, conduct policy, and issue forms live at the repository root. Packaging
includes the canonical root LICENSE in every tarball. Published entry points and deep imports are
under `lib/<name>`.
## Release preparation
All three packages share a version, with exact internal dependencies. Set a specific version:
```powershell
npm run version:set -- <version>
```
Or increment the shared patch version:
```powershell
npm run version:patch
```
Update each package's `CHANGELOG.md` for the new version and review the manifest and lockfile
changes. Then build and validate the release:
```powershell
npm ci --ignore-scripts
npm run clean
npm run build
npm run lint
npm test
npm run validate:release
```
Packaging requires existing build outputs and never builds, commits, tags, pushes, or publishes.
Release commands use `scripts/release-cli.ts`; reusable release helpers remain in `scripts/release.ts`.
`validate:release` packs and validates the release; use `pack:release` when only packaging is needed.
Use the configured npm registry for the root restore and isolated consumer install.
The three tarballs and `dist/release-manifest.json` form one release set. The validation command
packs and installs all three tarballs together in an isolated consumer outside the workspaces.
Tarballs are written to `dist/npm/<package-name>/*.tgz`. The schema-v1 manifest records the shared
version, source commit, package metadata, and SHA-512 integrity. Its `workspace` paths are relative
to the repository root; `tarball` paths are relative to `dist`.
Version preparation updates all manifests and exact internal dependencies together and refreshes
the lockfile. Stable versions use the `latest` tag; prereleases use `next`. `version:patch` follows
SemVer rules, including promoting a prerelease patch to its stable version.
## Related projects
- [vscode-powerquery](https://github.com/microsoft/vscode-powerquery): Power Query language support for VS Code.
- [vscode-powerquery-sdk](https://github.com/microsoft/vscode-powerquery-sdk): Power Query connector SDK.
## Contributing
This project welcomes contributions and suggestions. Most contributions require a
[Contributor License Agreement](https://cla.opensource.microsoft.com). The CLA bot identifies
whether one is needed when you submit a pull request.
This project follows the [Microsoft Open Source Code of Conduct](CODE_OF_CONDUCT.md).
See the [FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact
[opencode@microsoft.com](mailto:opencode@microsoft.com) with questions.