Add upstream compatibility baseline check and commit-trace helpers

.github/workflows/dev-containers.yml

@@ -28,6 +28,8 @@ jobs:
         scope: '@microsoft'
     - name: Install Dependencies
       run: yarn install --frozen-lockfile
+    - name: Upstream Compatibility Baseline
+      run: yarn check-upstream-compatibility
     - name: Type-Check
       run: yarn type-check
     - name: Lint

README.md

@@ -15,6 +15,22 @@ When updating upstream, prefer an explicit workflow:
 3. Fix regressions in project-owned code.
 4. Merge once CI is green.
 
+Recommended command sequence:
+
+```bash
+git submodule update --init --recursive
+git -C upstream fetch origin
+git -C upstream checkout <new-upstream-commit>
+git add upstream
+git rev-parse HEAD:upstream
+npm run check-upstream-compatibility
+npm test
+```
+
+If `npm run check-upstream-compatibility` reports a commit change, update
+[`docs/upstream/compatibility-baseline.json`](./docs/upstream/compatibility-baseline.json)
+in the same change after parity checks pass.
+
 If you clone this repository without submodules, initialize them before building/testing:
 
 ```bash

TODO.md

@@ -204,9 +204,12 @@ Move all vendored upstream TypeScript CLI sources out of repo root and treat `up
 ### 3) Compatibility target versioning
 - [x] Define the compatibility contract as: “this repo targets the exact commit pinned in `upstream/`.”
   - Added `resolvePinnedUpstreamCommit(...)` and `formatUpstreamCompatibilityContract(...)` helpers (with tests) to make the pinned-commit contract explicit and machine-resolvable.
-- [ ] Expose the pinned upstream commit in test output/logging for traceability.
-- [ ] Add a dedicated CI check that reports diffs/regressions when submodule commit changes.
-- [ ] Create an “update upstream” workflow (bump submodule -> run parity suite -> fix breakages -> merge).
+- [x] Expose the pinned upstream commit in test output/logging for traceability.
+  - Added `formatUpstreamCommitTraceLine(...)` and a CI-emitted `[upstream-compat] pinned upstream commit: ...` log line so pinned commit traces appear in automated output.
+- [x] Add a dedicated CI check that reports diffs/regressions when submodule commit changes.
+  - Added `build/check-upstream-compatibility.js`, baseline metadata in `docs/upstream/compatibility-baseline.json`, npm script `check-upstream-compatibility`, and wired it into the CI workflow.
+- [x] Create an “update upstream” workflow (bump submodule -> run parity suite -> fix breakages -> merge).
+  - Expanded `README.md` with a concrete command sequence for submodule bump, compatibility checks, parity tests, and baseline update expectations.
 
 ### 4) Documentation updates
 - [ ] Update `README.md` with:

build/check-upstream-compatibility.js

@@ -0,0 +1,55 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const cp = require('child_process');
+
+const repositoryRoot = path.join(__dirname, '..');
+const baselineFilePath = path.join(repositoryRoot, 'docs/upstream/compatibility-baseline.json');
+const submodulePath = 'upstream';
+
+function fail(message) {
+	console.error(message);
+	process.exit(1);
+}
+
+function resolveCurrentPinnedCommit() {
+	return cp.execFileSync('git', ['rev-parse', `:${submodulePath}`], {
+		cwd: repositoryRoot,
+		encoding: 'utf8',
+		stdio: ['ignore', 'pipe', 'pipe'],
+	}).trim();
+}
+
+if (!fs.existsSync(baselineFilePath)) {
+	fail(`Missing compatibility baseline file: ${path.relative(repositoryRoot, baselineFilePath)}`);
+}
+
+const baselineRaw = fs.readFileSync(baselineFilePath, 'utf8');
+/** @type {{ submodulePath?: string; pinnedCommit?: string; compatibilityContract?: string; }} */
+const baseline = JSON.parse(baselineRaw);
+
+if (!baseline.pinnedCommit || typeof baseline.pinnedCommit !== 'string') {
+	fail(`Invalid pinnedCommit in ${path.relative(repositoryRoot, baselineFilePath)}`);
+}
+
+const currentCommit = resolveCurrentPinnedCommit();
+const recordedCommit = baseline.pinnedCommit.trim();
+
+console.log(`[upstream-compat] pinned upstream commit: ${currentCommit}`);
+
+if (recordedCommit !== currentCommit) {
+	fail(
+		[
+			`Pinned upstream commit changed from ${recordedCommit} to ${currentCommit}.`,
+			'Run parity tests and update docs/upstream/compatibility-baseline.json in the same change.',
+		].join('\n'),
+	);
+}
+
+console.log('[upstream-compat] compatibility baseline matches pinned upstream commit.');

docs/upstream/compatibility-baseline.json

@@ -0,0 +1,5 @@
+{
+  "submodulePath": "upstream",
+  "pinnedCommit": "39685cf1aa58b5b11e90085bd32562fad61f4103",
+  "compatibilityContract": "This repository targets upstream/ at commit 39685cf1aa58b5b11e90085bd32562fad61f4103."
+}

package.json

@@ -43,7 +43,8 @@
 		"test-container-features-cli": "env TS_NODE_PROJECT=upstream/src/test/tsconfig.json mocha -r ts-node/register --exit upstream/src/test/container-features/featuresCLICommands.test.ts",
 		"test-container-templates": "env TS_NODE_PROJECT=upstream/src/test/tsconfig.json mocha -r ts-node/register --exit upstream/src/test/container-templates/*.test.ts",
 		"check-setup-separation": "node build/check-setup-separation.js",
-		"check-upstream-submodule": "node build/check-upstream-submodule.js"
+		"check-upstream-submodule": "node build/check-upstream-submodule.js",
+		"check-upstream-compatibility": "node build/check-upstream-compatibility.js"
 	},
 	"files": [
 		"CHANGELOG.md",

src/spec-node/migration/upstreamCompatibility.ts

@@ -29,3 +29,31 @@ export function resolvePinnedUpstreamCommit(options: ResolvePinnedUpstreamCommit
 export function formatUpstreamCompatibilityContract(commit: string) {
 	return `This repository targets upstream/ at commit ${commit}.`;
 }
+
+export function formatUpstreamCommitTraceLine(commit: string) {
+	return `[upstream-compat] pinned upstream commit: ${commit}`;
+}
+
+interface UpstreamCommitRegressionInput {
+	recordedCommit: string;
+	currentCommit: string;
+}
+
+interface UpstreamCommitRegressionReport {
+	hasRegression: boolean;
+	summary: string;
+}
+
+export function reportUpstreamCommitRegression(input: UpstreamCommitRegressionInput): UpstreamCommitRegressionReport {
+	if (input.recordedCommit === input.currentCommit) {
+		return {
+			hasRegression: false,
+			summary: `Pinned upstream commit unchanged at ${input.currentCommit}.`,
+		};
+	}
+
+	return {
+		hasRegression: true,
+		summary: `Pinned upstream commit changed from ${input.recordedCommit} to ${input.currentCommit}.`,
+	};
+}

src/test/upstreamCompatibility.test.ts

@@ -1,7 +1,9 @@
 import { expect } from 'chai';
 
 import {
+	formatUpstreamCommitTraceLine,
 	formatUpstreamCompatibilityContract,
+	reportUpstreamCommitRegression,
 	resolvePinnedUpstreamCommit,
 } from '../spec-node/migration/upstreamCompatibility';
 
@@ -25,6 +27,31 @@ describe('upstream compatibility contract helpers', () => {
 		);
 	});
 
+	it('formats a traceable pinned commit log line', () => {
+		const line = formatUpstreamCommitTraceLine('0123456789abcdef0123456789abcdef01234567');
+		expect(line).to.equal('[upstream-compat] pinned upstream commit: 0123456789abcdef0123456789abcdef01234567');
+	});
+
+	it('reports a regression summary when pinned commit changes', () => {
+		const report = reportUpstreamCommitRegression({
+			recordedCommit: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+			currentCommit: 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb',
+		});
+		expect(report.hasRegression).to.equal(true);
+		expect(report.summary).to.equal(
+			'Pinned upstream commit changed from aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa to bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb.',
+		);
+	});
+
+	it('reports no regression when pinned commit is unchanged', () => {
+		const report = reportUpstreamCommitRegression({
+			recordedCommit: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+			currentCommit: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+		});
+		expect(report.hasRegression).to.equal(false);
+		expect(report.summary).to.equal('Pinned upstream commit unchanged at aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.');
+	});
+
 	it('throws when git output is empty', () => {
 		expect(() => resolvePinnedUpstreamCommit({
 			repositoryRoot: '/workspace/devcontainer-cli',