Clarify Node version requirements

.gitignore

@@ -11,6 +11,7 @@ coverage
 profile*.json
 .yarn/*
 !.yarn/patches/
+!.yarn/plugins/
 !.yarn/releases/
 temp
 *.tgz

.yarn/plugins/@yarnpkg/plugin-engines.cjs

@@ -0,0 +1,11 @@
+/* eslint-disable */
+//prettier-ignore
+module.exports = {
+name: "@yarnpkg/plugin-engines",
+factory: function (require) {
+"use strict";var plugin=(()=>{var x=Object.create;var v=Object.defineProperty;var V=Object.getOwnPropertyDescriptor;var U=Object.getOwnPropertyNames;var z=Object.getPrototypeOf,B=Object.prototype.hasOwnProperty;var u=(e=>typeof require<"u"?require:typeof Proxy<"u"?new Proxy(e,{get:(o,t)=>(typeof require<"u"?require:o)[t]}):e)(function(e){if(typeof require<"u")return require.apply(this,arguments);throw Error('Dynamic require of "'+e+'" is not supported')});var _=(e,o)=>{for(var t in o)v(e,t,{get:o[t],enumerable:!0})},O=(e,o,t,d)=>{if(o&&typeof o=="object"||typeof o=="function")for(let a of U(o))!B.call(e,a)&&a!==t&&v(e,a,{get:()=>o[a],enumerable:!(d=V(o,a))||d.enumerable});return e};var C=(e,o,t)=>(t=e!=null?x(z(e)):{},O(o||!e||!e.__esModule?v(t,"default",{value:e,enumerable:!0}):t,e)),j=e=>O(v({},"__esModule",{value:!0}),e);var Y={};_(Y,{default:()=>X});var s=u("@yarnpkg/core"),I=u("@yarnpkg/fslib"),W=C(u("path")),T=C(u("semver"));var L=C(u("semver"));function H(e){try{let o=new L.default.Range(e||"");return o.range||o.raw==="*"?o:null}catch{return null}}function A(e){let{repoRange:o,manifestRange:t}=e,d=H(t);return!d||L.default.subset(o,d)}var G={engines:{description:"Config for yarn-plugin-engines",type:s.SettingsType.SHAPE,properties:{ignorePackages:{description:"List of packages to ignore when validating engines.node (also ignores their dependencies)",type:s.SettingsType.STRING,isArray:!0,default:[]},includeDevDependencies:{description:"Whether to include local dev dependencies and private packages when validating engines.node",type:s.SettingsType.BOOLEAN,default:!1},verbose:{description:"Enable verbose warnings for debugging",type:s.SettingsType.BOOLEAN,default:!1}}}},q=new I.NodeFS,Q=async(e,o)=>{let t=e.configuration.get("engines"),d=t?.get("ignorePackages")||[],a=!!t?.get("includeDevDependencies"),P=!!t?.get("verbose"),g=e.configuration.get("nodeLinker")||"node-modules",c=n=>{o.reportError(0,`[yarn-plugin-engines] ${String(n)}`)},f=n=>{P&&o.reportWarning(0,`[yarn-plugin-engines] warning: ${String(n)}`)};if(g!=="pnpm"&&g!=="node-modules"){c(`This plugin is not compatible with the ${g} linker`);return}let l=e.topLevelWorkspace.manifest.raw.engines?.node;if(!l){c("Missing package.json engines.node field");return}let p=H(l);if(!p){c(`Invalid semver range "${l}" in package.json engines.node`);return}if(!T.default.satisfies(process.versions.node,p)){c(`The current Node version ${process.versions.node} does not satisfy ${p.raw}`);return}let F=e.configuration.getLinkers().find(n=>n.supportsPackage(e.workspaces[0].anchoredPackage,{project:e})),h=[],S=new Set,M=new Set,w=(n,r)=>{let i=s.structUtils.stringifyIdent(n);n.range.startsWith("workspace:")||d.includes(i)||S.has(n.descriptorHash)||h.includes(n.descriptorHash)||(h.push(n.descriptorHash),(r.raw.optionalDependencies?.[i]||r.raw.dependenciesMeta?.[i]?.optional===!0||r.raw.peerDependenciesMeta?.[i]?.optional===!0)&&M.add(n.descriptorHash))};for(let n of e.workspaces){if(n.manifest.private&&!a)continue;let r=e.storedPackages.get(n.anchoredLocator.locatorHash);if(r){for(let i of r.dependencies.values())(a||n.manifest.dependencies.has(i.identHash))&&w(i,n.manifest);for(let i of r.peerDependencies.values())w(i,n.manifest)}}let b={};for(;h.length;){let n=h.shift();S.add(n);let r=M.has(n),i=$=>!r&&c($),N=e.storedDescriptors.get(n);if(!N){i(`Could not find descriptor for hash ${n}`);continue}let k=s.structUtils.prettyDescriptor(e.configuration,N),E=e.storedResolutions.get(n);if(!E){i(`Could not find a resolved version for ${k}`);continue}let m=e.storedPackages.get(E);if(!m){i(`Could not find an installed package for ${k}`);continue}let D=await J(m,{project:e,report:o,linker:F,isOptional:r,verboseWarning:f});if(!D){i(`Could not find location for ${k}`);continue}let R=await s.Manifest.tryFind(D,{baseFs:q});if(!R){c(`Could not find package.json for ${k} at ${D}`);continue}let y=R.raw.engines?.node;y&&!A({repoRange:p,manifestRange:y})&&(b[y]??=new Set,b[y].add(s.structUtils.prettyLocator(e.configuration,m)));for(let $ of m.dependencies.values())w($,R)}for(let[n,r]of Object.entries(b))c(`The following packages require Node ${n}, which does not match the repo requirement ${p.raw}:
+`+[...r].sort().map(i=>`  - ${i}`).join(`
+`))};async function J(e,o){let{project:t,report:d,linker:a,isOptional:P,verboseWarning:g}=o,c=s.structUtils.prettyLocator(t.configuration,e);try{return await a.findPackageLocation(e,{project:t,report:d})}catch(l){if(P){g(`Could not find location for optional package ${c}, skipping...`);return}if(s.structUtils.isVirtualLocator(e)){g(`Could not find location for ${c} - trying devirtualized locator... (original error: ${l})`);try{let p=s.structUtils.devirtualizeLocator(e);return await a.findPackageLocation(p,{project:t,report:d})}catch{}}}let f=W.default.join(t.cwd,"node_modules",s.structUtils.stringifyIdent(e));if(q.existsSync(f))return g(`Falling back to node_modules path for ${c}: ${f}`),f}var K={hooks:{validateProjectAfterInstall:Q},configuration:G},X=K;return j(Y);})();
+return plugin;
+}
+};

.yarnrc.yml

@@ -1,3 +1,19 @@
 nodeLinker: node-modules
 
 yarnPath: .yarn/releases/yarn-4.12.0.cjs
+
+plugins:
+  # See plugin page for latest version: https://github.com/ecraig12345/yarn-plugins/tree/main/plugins/engines
+  # (Please revert yarn's automatic formatting changes to this file if updating the plugin...)
+  - checksum: d19a26e2cd1ce11ecaf6b3a91b6d07b0e613acd15aa9b4528eb80234153ae0987c5ce13c1019dea3a0df3beba978766865bbe63122d42d36ed201ad1691b7714
+    path: .yarn/plugins/@yarnpkg/plugin-engines.cjs
+    spec: "https://raw.githubusercontent.com/ecraig12345/yarn-plugins/engines_v0.1.4/plugins/engines/dist/plugin.js"
+
+engines:
+  ignorePackages:
+    # These and all related packages are incompatible with 16, but pinned to versions compatible
+    # with 18 as a compromise (they had been accidentally updated to versions requiring 18
+    # some time ago, and it's only an issue for scenarios using Azure blob storage caching)
+    - "@azure/core-auth"
+    - "@azure/identity"
+    - "@azure/storage-blob"

change/change-e216a4a6-375f-42f1-a2ab-ecf44aaf5987.json

@@ -0,0 +1,25 @@
+{
+  "changes": [
+    {
+      "type": "patch",
+      "comment": "Downgrade azure deps to Node 18-compatible versions",
+      "packageName": "@lage-run/cache",
+      "email": "elcraig@microsoft.com",
+      "dependentChangeType": "patch"
+    },
+    {
+      "type": "none",
+      "comment": "update readme",
+      "packageName": "@lage-run/globby",
+      "email": "elcraig@microsoft.com",
+      "dependentChangeType": "none"
+    },
+    {
+      "type": "minor",
+      "comment": "Add an explicit `engines` requirement of Node 16, though 18 is required if using Azure blob storage caching. (This accidentally drifted over time due to Yarn 4 not enforcing `engines`. Azure deps have now been downgraded to versions compatible with 18.)",
+      "packageName": "lage",
+      "email": "elcraig@microsoft.com",
+      "dependentChangeType": "patch"
+    }
+  ]
+}

docs/.yarnrc.yml

@@ -1,2 +1,3 @@
-yarnPath: ../.yarn/releases/yarn-4.8.0.cjs
 nodeLinker: node-modules
+
+yarnPath: ../.yarn/releases/yarn-4.12.0.cjs

docs/docs/cookbook/migration.mdx

@@ -21,32 +21,12 @@ Lage has many changes from 1.x to 2.x. This migration guide will go over major c
 
 ### Breaking Changes
 
-- `lage` requires **Node 16**, or using the `--experimental-abortcontroller` flag in Node 14
+- `lage` requires **Node 16** ~~or using the `--experimental-abortcontroller` flag in Node 14~~ (the intent was to continue Node 14 support, but this accidentally drifted over time due to Yarn 4 not enforcing that dependencies match the repo's `package.json` `engines`).
+  - As of writing, the practical minimum Node version is 18. This is most likely to be an issue if you're caching to Azure blob storage.
 - `lage` now will automatically write remote cache if the typical environment variable is set (e.g. `CI` or `TF_BUILD`)
 - `info` command is not implemented yet
 - `graph` command is not implemented yet
 
-#### Using `lage` v2 with Node 14
-
-If you're still on Node 14, you can use Lage v2 by wrapping it with a script which passes the `--experimental-abortcontroller` flag, and using that wrapper in your other scripts.
-
-Relevant parts of `package.json` (omit the comments):
-
-```jsonc title="package.json"
-{
-  "scripts": {
-    // cross-env sets environment variables on any platform
-    "lage": "cross-env NODE_OPTIONS=\"--experimental-abortcontroller\" lage",
-    // Be sure to use `yarn lage` rather than only `lage` in your other scripts!
-    "build": "yarn lage build"
-  },
-  "devDependencies": {
-    "cross-env": "^7.0.0",
-    "lage": "^2.0.0"
-  }
-}
-```
-
 ## v0.x -> v1.x
 
 <Badge>version 1</Badge>

docs/package.json

@@ -72,5 +72,8 @@
       }
     ]
   },
+  "engines": {
+    "node": ">=18"
+  },
   "packageManager": "yarn@4.12.0"
 }

package.json

@@ -51,26 +51,39 @@
     "typescript": "~5.9.3"
   },
   "resolutions": {
+    "@azure/core-auth": "1.9.0",
+    "@azure/core-client": "1.9.4",
+    "@azure/core-http-compat": "2.3.0",
+    "@azure/core-rest-pipeline": "1.21.0",
+    "@azure/core-tracing": "1.2.0",
+    "@azure/core-util": "1.12.0",
+    "@azure/core-xml": "1.4.5",
+    "@azure/logger": "1.2.0",
+    "@azure/storage-blob": "12.27.0",
     "@types/node@npm:*": "^16.0.0",
     "typescript@npm:>=5.0.2": "~5.9.3",
-    "node-gyp@npm:latest": "^11.0.0",
+    "node-gyp@npm:latest": "^9.0.0",
     "listr2@npm:^9.0.5": "9.0.3",
     "syncpack/minimatch@npm:9.0.5": "^9.0.6",
+    "tar@npm:^6.1.11": "^7.5.11",
+    "tar@npm:^6.1.2": "^7.5.11",
     "globby/fast-glob": "patch:fast-glob@npm%3A3.3.3#~/.yarn/patches/fast-glob-npm-3.3.3-2a653be532.patch"
   },
   "rationale": {
     "resolutions": {
+      "@azure/*": "Pin to newest versions compatible with Node 18",
       "node-gyp@npm:latest": "Stop pulling in other newer deps",
       "listr2@npm:^9.0.5": "Prevent pulling in cli-truncate@5 => string-width@8 which requires Node 20",
       "syncpack/minimatch@npm:9.0.5": "Unpin to fix security issue",
+      "tar": "Fix security issue (compatible API)",
       "globby/fast-glob": "Fix name collision in @lage-run/globby dts-bundle-generator'd types"
     }
   },
   "lint-staged": {
     "*": "prettier --write"
   },
   "engines": {
-    "node": ">=14.13.1"
+    "node": ">=16.14.0"
   },
   "packageManager": "yarn@4.12.0"
 }

packages/cache/package.json

@@ -18,8 +18,8 @@
     "lint": "monorepo-scripts lint"
   },
   "dependencies": {
-    "@azure/core-auth": "1.10.1",
-    "@azure/identity": "4.13.0",
+    "@azure/core-auth": "1.9.0",
+    "@azure/identity": "4.9.1",
     "@lage-run/config": "workspace:^",
     "@lage-run/logger": "workspace:^",
     "@lage-run/target-graph": "workspace:^",

packages/globby/README.md

@@ -1,3 +1,3 @@
 CommonJS wrapper of [`globby`](https://www.npmjs.com/package/globby) with caching support and all dependencies bundled.
 
-This should follow the newest version of `globby` compatible with Lage's minimum Node version. As of writing, that's Node 14 and `globby` 13.
+This should follow the newest version of `globby` compatible with Lage's minimum Node version. As of writing, that's Node 16 and `globby` 13.

packages/lage/RELEASE.md

@@ -15,7 +15,8 @@ Lage version 2 is now available at dist-tag `@latest`, featuring significant upd
 
 ## Breaking changes
 
-- `lage` requires **Node 16**, or using the `--experimental-abortcontroller` flag in Node 14
+- `lage` requires **Node 16**
+  - Over time, this accidentally crept up to 18 due to Yarn 4 not enforcing that dependencies match the repo's `package.json` `engines`. This is most likely to be an issue if you're caching to Azure blob storage.
 - `lage` now will automatically write remote cache if the typical environment variable is set (e.g. `CI` or `TF_BUILD`)
 - `info` command is not implemented yet
 - `graph` command is not implemented yet

packages/lage/package.json

@@ -33,5 +33,8 @@
   },
   "files": [
     "dist"
-  ]
+  ],
+  "engines": {
+    "node": ">=16.14.0"
+  }
 }

renovate.json5

@@ -6,7 +6,7 @@
     "github>microsoft/m365-renovate-config:disableEsmVersions",
     "github>microsoft/m365-renovate-config:groupMore",
     "github>microsoft/m365-renovate-config:keepFresh",
-    "github>microsoft/m365-renovate-config:restrictNode(14)"
+    "github>microsoft/m365-renovate-config:restrictNode(16)"
   ],
   "labels": ["renovate"],
   "prHourlyLimit": 5,
@@ -45,6 +45,11 @@
       // latest version, which yarn will dedupe to the in-repo version.
       "matchPackageNames": ["lage", "lage-npm"],
       "enabled": false
+    },
+    {
+      // Disable due to Node version compatibility
+      "matchPackageNames": ["@azure/*", "node-gyp"],
+      "enabled": false
     }
   ]
 }

scripts/config/eslintrc.js

@@ -19,6 +19,7 @@ const config = {
     "**/__fixtures__",
     "**/fixtures",
     "/*.js",
+    "/*.cjs",
     "**/yarn.js",
     "docs",
     "packages/*/scripts",