feat: add process docs and scripts for yarn.lock only backports

Signed-off-by: Jessica He <jhe@redhat.com>

Author: JessicaJHee

scripts/yarnlock-backport/.gitignore

@@ -0,0 +1 @@
+node_modules/

scripts/yarnlock-backport/README.md

@@ -0,0 +1,24 @@
+# yarnlock-backport
+
+Generate `0-cve-yarn-lock.patch` and `cve-backports.yaml` for overlay workspaces without bumping `source.json:repo-ref`.
+
+Full workflow: [user-guide/06-patch-management.md](../../user-guide/06-patch-management.md).
+
+```bash
+cd scripts/yarnlock-backport && npm install
+
+export OVERLAY_WORKSPACE=<absolute-path>/workspaces/orchestrator
+export PLUGINS_REPO=<absolute-path>
+
+yarnlock-backport prepare  --release 1.10 --overlay-workspace "$OVERLAY_WORKSPACE" --plugins-repo "$PLUGINS_REPO"
+# … yarn up in plugins workspace …
+yarnlock-backport generate --release 1.10 --overlay-workspace "$OVERLAY_WORKSPACE" --plugins-repo "$PLUGINS_REPO" --cve 'CVE-…,CVE-…'
+```
+
+Requires: Node.js, `git`, `yarn`, `patch`, `diff`, `npm`. `--overlay-workspace` and `--plugins-repo` must be **absolute** paths.
+
+Fork clones need an `upstream` remote pointing at `https://github.com/redhat-developer/rhdh-plugin-export-overlays.git` (step 0 syncs the release branch from there).
+
+```bash
+npm test
+```

scripts/yarnlock-backport/backport.test.ts

@@ -0,0 +1,203 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  assertPathWithin,
+  normalizeCveId,
+  parseCveArg,
+  parseCveCliToken,
+  parseCveDetails,
+  releaseBranch,
+  requireLockfileChange,
+  resolveCliPath,
+  resolveOverlayGitRemote,
+  resolvePluginsGitRemote,
+  validateGitRef,
+  validateReleaseBranch,
+  validateWorkspaceName,
+} from './backport.ts';
+import { mkdtempSync, realpathSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+describe('requireLockfileChange', () => {
+  it('accepts when baseline and patched differ', () => {
+    assert.doesNotThrow(() => requireLockfileChange('a', 'b'));
+  });
+
+  it('rejects when lockfile is unchanged from repo-ref', () => {
+    assert.throws(() => requireLockfileChange('same', 'same'), /yarn.lock unchanged from repo-ref baseline/);
+  });
+});
+
+describe('resolveOverlayGitRemote', () => {
+  const forkRemotes = `origin\tgit@github.com:JessicaJHee/rhdh-plugin-export-overlays.git (fetch)
+origin\tgit@github.com:JessicaJHee/rhdh-plugin-export-overlays.git (push)
+upstream\thttps://github.com/redhat-developer/rhdh-plugin-export-overlays.git (fetch)
+upstream\thttps://github.com/redhat-developer/rhdh-plugin-export-overlays.git (push)`;
+
+  it('prefers upstream on fork clones', () => {
+    assert.equal(
+      resolveOverlayGitRemote(forkRemotes, 'git@github.com:JessicaJHee/rhdh-plugin-export-overlays.git'),
+      'upstream',
+    );
+  });
+
+  it('uses origin for direct upstream clones', () => {
+    const remotes = `origin\thttps://github.com/redhat-developer/rhdh-plugin-export-overlays.git (fetch)`;
+    assert.equal(
+      resolveOverlayGitRemote(remotes, 'https://github.com/redhat-developer/rhdh-plugin-export-overlays.git'),
+      'origin',
+    );
+  });
+
+  it('errors when fork has no upstream remote', () => {
+    const remotes = `origin\tgit@github.com:JessicaJHee/rhdh-plugin-export-overlays.git (fetch)`;
+    assert.throws(
+      () => resolveOverlayGitRemote(remotes, 'git@github.com:JessicaJHee/rhdh-plugin-export-overlays.git'),
+      /no upstream remote/,
+    );
+  });
+});
+
+describe('resolvePluginsGitRemote', () => {
+  it('prefers upstream on fork clones', () => {
+    const remotes = `origin\tgit@github.com:JessicaJHee/rhdh-plugins.git (fetch)
+upstream\thttps://github.com/redhat-developer/rhdh-plugins.git (fetch)`;
+    assert.equal(resolvePluginsGitRemote(remotes, 'git@github.com:JessicaJHee/rhdh-plugins.git'), 'upstream');
+  });
+});
+
+describe('releaseBranch', () => {
+  it('maps release version to branch name', () => {
+    assert.equal(releaseBranch('1.10'), 'release-1.10');
+  });
+
+  it('accepts branch name as-is', () => {
+    assert.equal(releaseBranch('release-1.10'), 'release-1.10');
+  });
+
+  it('rejects empty release', () => {
+    assert.throws(() => releaseBranch('  '), /release is empty/);
+  });
+});
+
+describe('validateReleaseBranch', () => {
+  it('accepts semver release versions', () => {
+    assert.equal(validateReleaseBranch('1.10'), 'release-1.10');
+    assert.equal(validateReleaseBranch('1.10.2'), 'release-1.10.2');
+  });
+
+  it('rejects unsafe branch suffixes', () => {
+    assert.throws(() => validateReleaseBranch('release-1.10;rm -rf'), /invalid release version/);
+  });
+});
+
+describe('resolveCliPath', () => {
+  it('requires absolute paths', () => {
+    assert.throws(() => resolveCliPath('relative/path', 'test'), /path must be absolute/);
+  });
+
+  it('resolves existing absolute paths', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'yarnlock-backport-test-'));
+    try {
+      const abs = realpathSync(dir);
+      assert.equal(resolveCliPath(abs, 'test'), abs);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('assertPathWithin', () => {
+  it('allows child paths within parent', () => {
+    const parent = resolve('/tmp/repo');
+    const child = join(parent, 'workspaces', 'orchestrator');
+    assert.doesNotThrow(() => assertPathWithin(child, parent, 'test'));
+  });
+
+  it('rejects paths that escape parent', () => {
+    assert.throws(
+      () => assertPathWithin(resolve('/tmp/other'), resolve('/tmp/repo'), 'test'),
+      /path escapes allowed directory/,
+    );
+  });
+});
+
+describe('validateGitRef', () => {
+  it('accepts commit SHAs', () => {
+    assert.equal(validateGitRef('eb6cce1234567890abcdef'), 'eb6cce1234567890abcdef');
+  });
+
+  it('accepts tag names', () => {
+    assert.equal(validateGitRef('v1.2.3'), 'v1.2.3');
+  });
+
+  it('rejects path traversal', () => {
+    assert.throws(() => validateGitRef('../../../etc/passwd'), /invalid git ref/);
+  });
+});
+
+describe('validateWorkspaceName', () => {
+  it('accepts workspace directory names', () => {
+    assert.equal(validateWorkspaceName('orchestrator'), 'orchestrator');
+  });
+
+  it('rejects unsafe names', () => {
+    assert.throws(() => validateWorkspaceName('../escape'), /invalid workspace name/);
+  });
+});
+
+describe('normalizeCveId', () => {
+  it('accepts valid CVE ids', () => {
+    assert.equal(normalizeCveId('cve-2026-1234'), 'CVE-2026-1234');
+  });
+
+  it('rejects invalid CVE ids', () => {
+    assert.throws(() => normalizeCveId('not-a-cve'), /not a CVE id/);
+  });
+});
+
+describe('parseCveCliToken', () => {
+  it('parses CVE id without package override', () => {
+    assert.deepEqual(parseCveCliToken('CVE-2026-1234'), ['CVE-2026-1234', []]);
+  });
+
+  it('parses package override after slash', () => {
+    assert.deepEqual(parseCveCliToken('CVE-2026-1234/axios'), ['CVE-2026-1234', ['axios']]);
+  });
+});
+
+describe('parseCveArg', () => {
+  it('rejects duplicate CVE ids', () => {
+    assert.throws(() => parseCveArg('CVE-2026-1234,CVE-2026-1234'), /duplicate CVE/);
+  });
+});
+
+describe('parseCveDetails', () => {
+  it('returns empty details for rejected CVE records', () => {
+    const result = parseCveDetails({ cveMetadata: { state: 'REJECTED' }, containers: { cna: {} } });
+    assert.equal(result.name, '');
+    assert.deepEqual(result.patch_versions, []);
+  });
+
+  it('extracts lessThan fix version', () => {
+    const result = parseCveDetails({
+      cveMetadata: { state: 'PUBLISHED' },
+      containers: {
+        cna: {
+          affected: [{ packageName: 'axios', versions: [{ status: 'affected', version: '0', lessThan: '1.18.1' }] }],
+        },
+      },
+    });
+    assert.equal(result.name, 'axios');
+    assert.deepEqual(result.patch_versions, ['1.18.1']);
+  });
+});
+
+describe('maxVersion', () => {
+  it('orders semver-like versions numerically', () => {
+    const sorted = ['1.10.0', '1.9.0', '1.18.1'].sort((a, b) => a.localeCompare(b, undefined, { numeric: true }));
+    assert.deepEqual(sorted, ['1.9.0', '1.10.0', '1.18.1']);
+  });
+});