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=../../workspaces/orchestrator
+export PLUGINS_REPO=~/git/rhdh-plugins
+
+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`.
+
+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,120 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { normalizeCveId, parseCveArg, parseCveCliToken, parseCveDetails, releaseBranch, requireLockfileChange, resolveOverlayGitRemote, resolvePluginsGitRemote } from './backport.ts';
+
+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('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']);
+  });
+});