ci(ts-migration): guard migrated legacy paths

[cv]

Summary

• add a CI guard that blocks edits to migrated legacy JS implementation paths
• block new test/*.test.js additions or edits now that root tests are canonical .ts
• print actionable remediation pointing contributors at npm run ts-migration:assist

Testing

• npm run build:cli
• npm run typecheck:cli
• npm run lint
• npm run ts-migration:guard -- --base origin/ts-migration/10-pr-rescue-tooling --head HEAD
• npm test

Summary by CodeRabbit

• Chores
  • Added pull request validation that runs when targeting main. Automated checks provide detailed error messages with remediation guidance when issues are detected in CI logs.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds a GitHub Actions workflow with supporting scripts to prevent modifications to legacy migrated code paths. The workflow automatically runs on pull requests targeting main (excluding migration branches) and enforces that already-migrated paths are not edited by blocking non-migration PRs that attempt to modify those paths.

Changes

Cohort / File(s)	Summary
GitHub Actions Workflow .github/workflows/legacy-path-guard.yaml	New workflow that runs on PR events (opened, synchronize, reopened, ready_for_review). Conditionally executes on main-targeting PRs excluding migration branches. Sets up Node.js 22, fetches full repo history and base branch, then runs the guard check script to block legacy path edits.
Guard Implementation package.json, scripts/check-legacy-migrated-paths.ts	Added npm script ts-migration:guard that runs the new TypeScript guard script. Script parses CLI arguments (--base, --head), executes git diff to find changed files, maps them against move-map.json for migrated paths, validates against test files, and exits with code 1 if legacy paths were modified. Can be skipped via NEMOCLAW_ALLOW_LEGACY_PATHS=1 environment variable.

Sequence Diagram

sequenceDiagram
    actor GitHub as GitHub Actions
    participant Workflow as legacy-path-guard<br/>Workflow
    participant Script as check-legacy-<br/>migrated-paths.ts
    participant Git as Git Command
    participant Validator as Path Validator

    GitHub->>Workflow: PR event (opened/sync/reopened)
    Workflow->>Workflow: Check: target=main<br/>& !ts-migration/*
    alt Conditions Not Met
        Workflow->>GitHub: Skip job
    else Conditions Met
        Workflow->>Workflow: Checkout repo (fetch-depth: 0)
        Workflow->>Workflow: Setup Node.js 22
        Workflow->>Workflow: npm install --ignore-scripts
        Workflow->>Workflow: Fetch base branch (--depth=1)
        Workflow->>Script: npm run ts-migration:guard
        Script->>Script: Parse --base & --head args
        Script->>Git: git diff --name-only base...head
        Git->>Script: Return changed file paths
        Script->>Validator: Map legacy paths via move-map.json
        Validator->>Validator: Check test/*.test.js → .ts conversions
        alt Legacy paths detected
            Validator->>Script: Legacy edits found
            Script->>GitHub: Exit code 1 + error message
            GitHub->>GitHub: Block PR
        else No legacy paths
            Script->>GitHub: Exit code 0 + success message
            GitHub->>GitHub: Allow PR
        end
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 A guard hops in to protect the path,
Where TypeScript migrations take their bath,
No legacy edits slip on through,
The guard ensures the code stays true! ✨
Migration branches get a free pass,
While others must walk the righteous grass. 🛡️

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding a CI guard to prevent edits to TypeScript-migrated legacy paths, which is the core purpose of all three file additions.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch ts-migration/11-legacy-path-guard

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

.github/workflows/legacy-path-guard.yaml (2)

10-15: Set explicit minimal workflow permissions.

Consider adding a top-level permissions block (for example, contents: read) to keep GITHUB_TOKEN scope least-privileged.

Suggested fix

 on:
   pull_request:
     types: [opened, synchronize, reopened, ready_for_review]
+
+permissions:
+  contents: read
 
 jobs:
   guard-migrated-paths:

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.github/workflows/legacy-path-guard.yaml around lines 10 - 15, Add a
top-level minimal permissions block to the workflow to limit GITHUB_TOKEN scope
(for example, add permissions: contents: read) so the job "guard-migrated-paths"
runs with least-privileged access; place the permissions block at the top level
of the workflow YAML (parallel to "jobs") and ensure it grants only the required
permission(s) instead of using default full token scope.

---

28-29: Prefer npm ci for deterministic CI installs.

At Line 29, npm ci --ignore-scripts is typically faster and lockfile-strict for PR guard jobs.

Suggested fix

-      - name: Install root dependencies
-        run: npm install --ignore-scripts
+      - name: Install root dependencies
+        run: npm ci --ignore-scripts

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.github/workflows/legacy-path-guard.yaml around lines 28 - 29, Replace the
"Install root dependencies" step's command to use the lockfile-aware,
deterministic installer: change the run command in that step from "npm install
--ignore-scripts" to "npm ci --ignore-scripts" so CI uses the package-lock.json
for reproducible installs.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@scripts/check-legacy-migrated-paths.ts`:
- Around line 21-28: The parsing of CLI flags silently falls back to defaults
when "--base" or "--head" are missing a trailing value; update the argument
handling where argv, index, base and head are used to validate that argv[index +
1] exists and is not another flag (e.g., does not start with "--") before
assigning; if the value is missing or looks like a flag, print a clear error and
exit non-zero (or throw) rather than using the default so invocation mistakes
are surfaced in CI/debug; change the blocks that handle "--base" and "--head"
accordingly to perform this validation and error handling.

---

Nitpick comments:
In @.github/workflows/legacy-path-guard.yaml:
- Around line 10-15: Add a top-level minimal permissions block to the workflow
to limit GITHUB_TOKEN scope (for example, add permissions: contents: read) so
the job "guard-migrated-paths" runs with least-privileged access; place the
permissions block at the top level of the workflow YAML (parallel to "jobs") and
ensure it grants only the required permission(s) instead of using default full
token scope.
- Around line 28-29: Replace the "Install root dependencies" step's command to
use the lockfile-aware, deterministic installer: change the run command in that
step from "npm install --ignore-scripts" to "npm ci --ignore-scripts" so CI uses
the package-lock.json for reproducible installs.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: fb95d6a0-8263-44ee-9384-604d74888f51

📥 Commits

Reviewing files that changed from the base of the PR and between cec2c09 and 6b956a7.

📒 Files selected for processing (3)

• .github/workflows/legacy-path-guard.yaml
• package.json
• scripts/check-legacy-migrated-paths.ts

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Validate that --base/--head always receive an explicit value.

At Line 21 and Line 26, a missing trailing value currently falls back silently to defaults, which can hide invocation mistakes in CI/debug runs.

Suggested fix

+function readFlagValue(argv: string[], index: number, flag: "--base" | "--head"): string {
+  const value = argv[index + 1];
+  if (!value || value.startsWith("--")) {
+    throw new Error(`Missing value for ${flag}`);
+  }
+  return value;
+}
+
 function parseArgs(argv: string[]): Options {
   let base = "origin/main";
   let head = "HEAD";
@@
     const arg = argv[index];
     if (arg === "--base") {
-      base = argv[index + 1] || base;
+      base = readFlagValue(argv, index, "--base");
       index += 1;
       continue;
     }
     if (arg === "--head") {
-      head = argv[index + 1] || head;
+      head = readFlagValue(argv, index, "--head");
       index += 1;
       continue;
     }

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	if (arg === "--base") {
	base = argv[index + 1] || base;
	index += 1;
	continue;
	}
	if (arg === "--head") {
	head = argv[index + 1] || head;
	index += 1;
	function readFlagValue(argv: string[], index: number, flag: "--base" | "--head"): string {
	const value = argv[index + 1];
	if (!value || value.startsWith("--")) {
	throw new Error(`Missing value for ${flag}`);
	}
	return value;
	}
	if (arg === "--base") {
	base = readFlagValue(argv, index, "--base");
	index += 1;
	continue;
	}
	if (arg === "--head") {
	head = readFlagValue(argv, index, "--head");
	index += 1;

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@scripts/check-legacy-migrated-paths.ts` around lines 21 - 28, The parsing of
CLI flags silently falls back to defaults when "--base" or "--head" are missing
a trailing value; update the argument handling where argv, index, base and head
are used to validate that argv[index + 1] exists and is not another flag (e.g.,
does not start with "--") before assigning; if the value is missing or looks
like a flag, print a clear error and exit non-zero (or throw) rather than using
the default so invocation mistakes are surfaced in CI/debug; change the blocks
that handle "--base" and "--head" accordingly to perform this validation and
error handling.