@sasjs/sas-language 0.1.0 → 0.2.1

package/README.md

@@ -1,19 +1,31 @@
 # SAS language support for editors
 
-`@sasjs/sas-language` provides completions, hover documentation and signatures for SAS.
+`@sasjs/sas-language` provides SAS language support in two forms, from one
+upstream source and one pinned commit:
 
-The data is resolved from the [SAS extension for Visual Studio Code](https://github.com/sassoftware/vscode-sas-extension)
-and refreshed on a schedule, so this package owns the vocabulary rather than
-depending on a language server bundle. It carries no runtime dependencies and
-uses no Node built-ins, so it runs unchanged in a browser, in Node, and in an
-editor extension.
+    data/      the vocabulary: completions, hover documentation, signatures
+    server/    the SAS language server, compiled from upstream source
+
+Both are resolved from the [SAS extension for Visual Studio Code](https://github.com/sassoftware/vscode-sas-extension)
+and refreshed on a schedule, so this package owns the language support rather than
+depending on an installed editor extension.
+
+The data is small, has no runtime dependencies and uses no Node built-ins, so it
+runs unchanged in a browser, in Node and in an editor extension. The server is the
+full language service - semantic tokens, diagnostics, context-aware completions -
+and is what an editor that wants a real parser loads.
 
 ## Why this exists
 
-An editor needs to know SAS. The alternatives were to bundle a 28 MB language
-server that also carries Python tooling, or to hand-maintain keyword lists. This
-package takes the third option: take the authoritative data, transform it into
-something cheap to load, and keep it current with a scheduled job.
+An editor needs to know SAS. The alternatives were to depend on an installed
+extension for the data, or to hand-maintain keyword lists. This package takes the
+authoritative data, transforms it into something cheap to load, and keeps it
+current with a scheduled job.
+
+The server is here for the same reason. Upstream publishes no built artifact - its
+`dist/` is ignored and it has no release assets - so anyone wanting the language
+service had to build it from source themselves. This package compiles it from the
+pinned commit and ships the result.
 
 ## Install
 
@@ -21,17 +33,19 @@ something cheap to load, and keep it current with a scheduled job.
 npm install @sasjs/sas-language
 ```
 
-Until the package is on the registry it can be taken from git, pinned to a
-commit:
+The registry tarball ships the compiled output, so nothing is built on install. It
+is roughly 6 MB compressed, carrying both the data and both server builds.
+
+A git install also works, but needs lifecycle scripts enabled, because the build
+output is not committed and `prepare` compiles it. A git install does not build the
+server, which takes a few minutes - run `npm run build:server` for that.
 
 ```
 npm install git+https://github.com/sasjs/sas-language.git#<commit>
 ```
 
-That works because `dist/` is committed, not built on install. It has to be: a
-consumer that sets `ignore-scripts=true` - as sasjs/server does - never runs the
-package's `prepare` script, so a git install would otherwise arrive with no
-compiled API at all.
+Note that npm rewrites a github git dependency to an ssh URL in the lockfile,
+which a CI without an ssh key cannot fetch, so prefer the registry.
 
 ## Use
 
@@ -58,6 +72,38 @@ const doc = docsFor(docs, 'abs')
 Every group is a separate path, so a bundler emits only the groups you import and
 the documentation as its own chunk.
 
+## The language server
+
+Two builds ship, because the two consumers run in different places:
+
+    server/browser/server.js   webworker build, for an editor in a browser
+    server/node/server.js      node build, run over IPC by a VS Code extension
+
+The node build is a fraction of the browser build, because the browser bundle
+inlines the Python stubs that the node build reads from disk.
+
+The server has to exist as a file on disk - a VS Code extension spawns it as a
+child process rather than importing it - so copy it out of the package at build
+time:
+
+```ts
+const serverModule = context.asAbsolutePath('server/node/server.js')
+
+const serverOptions: ServerOptions = {
+  run: { module: serverModule, transport: TransportKind.ipc }
+}
+const clientOptions: LanguageClientOptions = {
+  documentSelector: [{ language: 'sas' }]
+}
+
+new LanguageClient('sas-lsp', 'SAS', serverOptions, clientOptions).start()
+```
+
+`server/provenance.json` records the commit both builds came from. It also
+records `byteReproducible: false`: the upstream loader inlines the Python stubs in
+filesystem order rather than sorting them, so the artifact is deterministic in
+content but not in bytes.
+
 ### Groups
 
 `GROUPS` lists every group with its label, completion kind and entry count.
@@ -116,7 +162,63 @@ not degrade somebody's editor.
     npm run build     # transform into data/ and compile
     npm test          # validate the data and the transforms
 
+The server is compiled from the same pin, by `npm run build:server`. That step is
+heavier - it fetches upstream at the commit, installs its dependencies and runs its
+build - so it is deliberately not part of `npm run build`. It runs in CI when the
+build or the pin changes, weekly against the latest upstream, and before any
+publish.
+
+## Repository hardening
+
+`.npmrc` installs without running lifecycle scripts, writes exact versions, enforces the `engines` field, and keeps the lockfile honest.
+
+`.git-hooks/` carries the org's checks: a `pre-commit` that scans the staged diff with gitleaks and refuses a commit over 2MB, and a `commit-msg` that enforces Conventional Commits. `npm run prepare` wires them up, but `.npmrc` sets `ignore-scripts=true`, which suppresses it - so after a fresh clone:
+
+```
+git config core.hooksPath ./.git-hooks
+```
+
+A hook is best-effort, so CI enforces the same things from the other side: a full-history `gitleaks detect`, `npm audit --omit=dev --audit-level=low` for the shipped surface, and `npm run audit` for everything else, dev dependencies included. That last one fails on any advisory outside two documented exemptions - see `scripts/audit.mjs` - so a new advisory anywhere else cannot land quietly.
+
+## Releasing
+
+`.github/workflows/publish.yml` publishes on every push to `main`.
+
+Versioning is semantic-release's job: it reads the conventional commits since the
+last tag, bumps the version, tags the release and writes the release notes.
+Publishing is a separate step, and it uses the npm trusted publisher, so no token
+is stored anywhere.
+
+Setup, once: on npmjs.com, add a trusted publisher for `@sasjs/sas-language` -
+repository `sasjs/sas-language`, workflow `publish.yml`, environment blank.
+
+semantic-release is configured **not** to push to `main`: `@semantic-release/git`
+is deliberately absent, so the version commit is never made and nothing needs to
+bypass branch protection. The release notes and the semantic versioning are
+unaffected - `@semantic-release/github` still publishes the grouped notes as the
+release body, and `@semantic-release/commit-analyzer` still maps `fix:` to a
+patch, `feat:` to a minor and a breaking change to a major. The one consequence
+is that `package.json` on `main` keeps the last committed version rather than the
+released one.
+
+Which commits cut a release follows the usual convention: `fix:` and `feat:` on
+`main` do, `chore:` and `ci:` do not. The refresh workflow opens a pull request,
+so merging it with a `fix:` or `feat:` subject is what cuts the next release.
+
+The publish step asks the registry first, so a push that produces no release
+reports that the version is already published and stays green, rather than
+failing with E403. When there is something to publish, it builds both the compiled
+API and the server, and refuses to publish if any artifact is missing.
+
+The workflow installs npm 11 before installing anything, because the trusted
+publisher needs 11.5.1 or later and a release should not adopt a new npm major on
+its own. `scripts/build-server.mjs` patches the upstream sub-build dispatch so the
+server builds on npm 11 and npm 12 alike; the pin keeps the release on the older
+of the two until the move is deliberate.
+
 ## Licence
 
-The package is MIT. The data is derived from the SAS extension for Visual Studio
-Code, which is Apache-2.0; see `NOTICE`.
+The package is MIT. Both the data and the compiled server come from the SAS
+extension for Visual Studio Code, which is Apache-2.0. The server also carries
+pyright (MIT), typeshed (Apache-2.0), buffer (MIT) and ieee754 (BSD-3-Clause); the
+licence texts travel with it in `server/`. See `NOTICE`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sasjs/sas-language",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "SAS language data for editors: completions, hover documentation and signatures, resolved from the SAS extension for VS Code",
   "license": "MIT",
   "type": "module",
@@ -16,15 +16,38 @@
       "default": "./dist/groups.js"
     },
     "./data/*": "./data/*",
+    "./server/browser": "./server/browser/server.js",
+    "./server/node": "./server/node/server.js",
     "./provenance.json": "./provenance.json"
   },
   "files": [
     "dist",
     "data",
+    "server",
     "provenance.json",
     "README.md"
   ],
   "sideEffects": false,
+  "overrides": {
+    "ip-address": "^10.5.1",
+    "undici": "^6.28.1"
+  },
+  "release": {
+    "branches": [
+      "main"
+    ],
+    "plugins": [
+      "@semantic-release/commit-analyzer",
+      "@semantic-release/release-notes-generator",
+      [
+        "@semantic-release/exec",
+        {
+          "prepareCmd": "npm version ${nextRelease.version} --no-git-tag-version"
+        }
+      ],
+      "@semantic-release/github"
+    ]
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -36,16 +59,22 @@
     "fetch": "node ./scripts/fetch-upstream.mjs",
     "build:data": "node ./scripts/build.mjs",
     "build:ts": "tsc -p ./tsconfig.json",
+    "build:server": "node ./scripts/build-server.mjs",
     "build": "npm run build:data && npm run build:ts",
     "refresh": "npm run fetch && npm run build:data",
-    "prepare": "npm run build:ts",
-    "test": "node --test ./test/*.test.mjs",
+    "audit": "node ./scripts/audit.mjs",
+    "prepare": "npm run build:ts && (git rev-parse --git-dir >/dev/null 2>&1 && git config core.hooksPath ./.git-hooks || true)",
+    "prepack": "npm run build:ts && npm run build:server",
+    "test": "npm run build:ts && node --test ./test/*.test.mjs",
     "lint": "prettier --check .",
     "lint:fix": "prettier --write ."
   },
   "devDependencies": {
-    "prettier": "^3.9.0",
-    "typescript": "^5.6.0"
+    "@nogoo9/gitleaks": "8.30.1-post.2",
+    "@semantic-release/exec": "7.1.0",
+    "prettier": "3.9.9",
+    "semantic-release": "25.0.9",
+    "typescript": "5.9.3"
   },
   "engines": {
     "node": ">=20"

package/server/LICENSE.pyright.txt

@@ -0,0 +1,22 @@
+pyright-internal (pyright)
+Copyright (c) Microsoft Corporation
+
+Licensed under the MIT License:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/server/LICENSE.server.js.txt

@@ -0,0 +1,8 @@
+/*!
+ * The buffer module from node.js, for the browser.
+ *
+ * @author   Feross Aboukhadijeh <https://feross.org>
+ * @license  MIT
+ */
+
+/*! ieee754. BSD-3-Clause License. Feross Aboukhadijeh <https://feross.org/opensource> */

package/server/LICENSE.txt

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.