@skyramp/mcp 0.3.4 → 0.3.6-rc.1

package/build/utils/changedRoutes.d.ts

@@ -0,0 +1,29 @@
+import { ScenarioStep } from "../types/RepositoryAnalysis.js";
+/** A method+path pair extracted from an actually-changed (`+`/`-`) diff line. */
+export interface ChangedRoute {
+    method: string;
+    path: string;
+}
+/**
+ * Extract method+path from every changed (`+`/`-`, non-header) line of a raw
+ * unified diff. Reuses `parseRouteLine`, which already strips the leading
+ * `+`/`-` marker and matches the same route-decorator patterns the endpoint
+ * scanner does.
+ */
+export declare function collectChangedRouteLines(diffText: string): ChangedRoute[];
+/**
+ * The first step of `steps` that targets a method+path on the changed hunk, or
+ * undefined. Returns the STEP, not a boolean, because two callers need
+ * different things from the same comparison: the ranker asks whether any step
+ * matches, and the subject resolver needs which ones do.
+ *
+ * Diff-extracted paths are local to the file's own router declaration (e.g.
+ * "/suggestions"); scenario step paths are fully mounted (e.g.
+ * "/api/recipes/suggestions"). A local path matches when the step path ends
+ * with it at a segment boundary (`pathSuffixMatches`), so the cross-file mount
+ * prefix difference (see recoverRemovedEndpointsFromBase, SKYR-4026) does not
+ * prevent the match — while a plain `endsWith` would also wrongly match an
+ * unrelated path that merely shares a trailing substring (e.g. "/preorders"
+ * against "orders").
+ */
+export declare function findStepOnChangedRoute(steps: ScenarioStep[] | undefined, changedRoutes: ChangedRoute[]): ScenarioStep | undefined;

package/build/utils/changedRoutes.js

@@ -0,0 +1,87 @@
+import { parseRouteLine, normalizeDiffPath } from "./routeParsers.js";
+import { isBareIdPath, pathSuffixMatches } from "./pathMatching.js";
+/**
+ * Extract method+path from every changed (`+`/`-`, non-header) line of a raw
+ * unified diff. Reuses `parseRouteLine`, which already strips the leading
+ * `+`/`-` marker and matches the same route-decorator patterns the endpoint
+ * scanner does.
+ */
+export function collectChangedRouteLines(diffText) {
+    const routes = [];
+    let currentFile = "";
+    let removedFile = "";
+    for (const line of diffText.split("\n")) {
+        // Track the current file from the unified-diff header so parseRouteLine
+        // gets the real path — its UI-component guard (UI_COMPONENT_EXT) depends
+        // on it, or a route-shaped line inside a .tsx/.jsx file (e.g. a client
+        // router registration) gets misparsed as a changed backend route.
+        // A deleted file has "+++ /dev/null", so the old side is the only name it
+        // has. Without it parseRouteLine gets an empty path and every
+        // extension-gated framework (Go, Rails, PHP) rejects the line, losing the
+        // routes the deletion removed.
+        if (line.startsWith("--- ")) {
+            const spec = line.slice(4).trim().split("\t")[0];
+            removedFile = spec === "/dev/null" ? "" : normalizeDiffPath(spec);
+            continue;
+        }
+        if (line.startsWith("+++ ")) {
+            const spec = line.slice(4).trim().split("\t")[0];
+            currentFile = spec === "/dev/null" ? removedFile : normalizeDiffPath(spec);
+            continue;
+        }
+        if (line.startsWith("diff --git") || line.startsWith("index "))
+            continue;
+        if (!(line.startsWith("+") || line.startsWith("-")))
+            continue;
+        const parsed = parseRouteLine(line, currentFile);
+        if (parsed)
+            routes.push({ method: parsed.method, path: parsed.path });
+    }
+    return routes;
+}
+/**
+ * The first step of `steps` that targets a method+path on the changed hunk, or
+ * undefined. Returns the STEP, not a boolean, because two callers need
+ * different things from the same comparison: the ranker asks whether any step
+ * matches, and the subject resolver needs which ones do.
+ *
+ * Diff-extracted paths are local to the file's own router declaration (e.g.
+ * "/suggestions"); scenario step paths are fully mounted (e.g.
+ * "/api/recipes/suggestions"). A local path matches when the step path ends
+ * with it at a segment boundary (`pathSuffixMatches`), so the cross-file mount
+ * prefix difference (see recoverRemovedEndpointsFromBase, SKYR-4026) does not
+ * prevent the match — while a plain `endsWith` would also wrongly match an
+ * unrelated path that merely shares a trailing substring (e.g. "/preorders"
+ * against "orders").
+ */
+export function findStepOnChangedRoute(steps, changedRoutes) {
+    if (changedRoutes.length === 0)
+        return undefined;
+    for (const step of steps ?? []) {
+        const stepMethod = (step.method ?? "").toUpperCase();
+        const stepPath = (step.path ?? "").replace(/\/+$/, "");
+        for (const route of changedRoutes) {
+            if (route.method.toUpperCase() !== stepMethod)
+                continue;
+            const routePath = route.path.replace(/\/+$/, "");
+            // A diff line declaring nothing but a bare id — `router.delete("/:id")`
+            // from a mounted Express router, `@Delete(":id")` from NestJS — names no
+            // resource, so it suffix-matches every `DELETE …/{id}` step. Both callers
+            // ask "does this changed route touch this step", and the answer there is
+            // no: for the ranker it lifted an unrelated candidate over a business-rule
+            // one, and for subject resolution it would make every step a subject.
+            // A NAMED parameter (`/:order_id`) still matches only its own resource,
+            // because the helper unifies a parameter's spelling and not its name.
+            if (isBareIdPath(routePath))
+                continue;
+            if (routePath === "") {
+                if (stepPath === "" || stepPath === "/")
+                    return step;
+                continue;
+            }
+            if (pathSuffixMatches(stepPath, routePath))
+                return step;
+        }
+    }
+    return undefined;
+}

package/build/utils/featureFlags.d.ts

@@ -66,3 +66,24 @@ export declare function isOneClickEnabled(): boolean;
  * the verification gates apply.
  */
 export declare function isPomReuseEnabled(): boolean;
+/**
+ * Gates SkyrampUtils code reuse for integration tests on the testbot path, and
+ * for UI tests whenever the POM path is off (SKYRAMP_FEATURE_UTILS_REUSE=1).
+ *
+ * When OFF (default), the testbot prompt does not set `codeReuse` on
+ * `skyramp_integration_test_generation` and its post-generation
+ * modularize→reuse step is disabled — integration tests are generated exactly
+ * as before, with no file-rewriting steps. UI tests keep their pre-existing
+ * single `skyramp_reuse_code` pass, which finds no helpers in inline Playwright
+ * output and no-ops.
+ *
+ * When ON, generated tests on modularize-first flows (see
+ * `isModularizeFirstTarget` in utils/reuseRouting.ts for which test types and
+ * flag combinations qualify) are modularized and their helpers consolidated
+ * into a shared SkyrampUtils file across sibling tests; the modularization
+ * prompts add canonical helper naming and the shared-helper assertion policy.
+ * On the NL path callers opt in per call via the `codeReuse` parameter, and the
+ * modularize-first routing still requires this flag — with it off, `codeReuse`
+ * yields the single reuse pass it did before the feature existed.
+ */
+export declare function isUtilsReuseEnabled(): boolean;

package/build/utils/featureFlags.js

@@ -76,3 +76,26 @@ export function isOneClickEnabled() {
 export function isPomReuseEnabled() {
     return process.env.SKYRAMP_FEATURE_POM_REUSE === "1";
 }
+/**
+ * Gates SkyrampUtils code reuse for integration tests on the testbot path, and
+ * for UI tests whenever the POM path is off (SKYRAMP_FEATURE_UTILS_REUSE=1).
+ *
+ * When OFF (default), the testbot prompt does not set `codeReuse` on
+ * `skyramp_integration_test_generation` and its post-generation
+ * modularize→reuse step is disabled — integration tests are generated exactly
+ * as before, with no file-rewriting steps. UI tests keep their pre-existing
+ * single `skyramp_reuse_code` pass, which finds no helpers in inline Playwright
+ * output and no-ops.
+ *
+ * When ON, generated tests on modularize-first flows (see
+ * `isModularizeFirstTarget` in utils/reuseRouting.ts for which test types and
+ * flag combinations qualify) are modularized and their helpers consolidated
+ * into a shared SkyrampUtils file across sibling tests; the modularization
+ * prompts add canonical helper naming and the shared-helper assertion policy.
+ * On the NL path callers opt in per call via the `codeReuse` parameter, and the
+ * modularize-first routing still requires this flag — with it off, `codeReuse`
+ * yields the single reuse pass it did before the feature existed.
+ */
+export function isUtilsReuseEnabled() {
+    return process.env.SKYRAMP_FEATURE_UTILS_REUSE === "1";
+}

package/build/utils/frontendIntegration.js

@@ -29,7 +29,7 @@ import * as path from "path";
 import { isTestFile, isI18nLocaleFile } from "../prompts/test-recommendation/scopeAssessment.js";
 import { logger } from "./logger.js";
 import { walkDir } from "./fileWalk.js";
-import { buildPathSignatures } from "./pathSignatures.js";
+import { buildPathSignatures, importsIndexModule, isIndexModule } from "./pathSignatures.js";
 import { IntegrationReason } from "../types/FrontendIntegration.js";
 const MAX_IMPORTERS = 10;
 const MAX_FILES_WALKED = 3000;
@@ -184,9 +184,11 @@ function checkOneFile(repositoryPath, file) {
     }
     try {
         const signatures = buildPathSignatures(file);
-        const importers = searchProductionImporters(repositoryPath, signatures)
-            .filter((candidate) => candidate !== file && !isExcludedImporterPath(candidate))
-            .slice(0, MAX_IMPORTERS);
+        const candidates = searchProductionImporters(repositoryPath, signatures)
+            .filter((candidate) => candidate !== file && !isExcludedImporterPath(candidate));
+        const importers = isIndexModule(file)
+            ? selectIndexModuleImporters(repositoryPath, file, candidates)
+            : candidates.slice(0, MAX_IMPORTERS);
         return {
             file,
             integrated: importers.length > 0,
@@ -202,6 +204,34 @@ function checkOneFile(repositoryPath, file) {
         return { file, integrated: true, importers: [], reason: IntegrationReason.ScanError };
     }
 }
+/**
+ * An index module's directory stem (`/_constants'`) is a plain string match, so a
+ * file importing its own unrelated `./_constants` also hits. Keep only candidates
+ * whose specifier resolves to this module's directory. Reads stop once
+ * MAX_IMPORTERS are accepted; files over MAX_FILE_SIZE_BYTES are skipped like in
+ * manualWalkGrep; an unreadable candidate is kept (fail-open, like the module).
+ */
+function selectIndexModuleImporters(repositoryPath, file, candidates) {
+    const accepted = [];
+    for (const candidate of candidates) {
+        if (accepted.length >= MAX_IMPORTERS)
+            break;
+        const abs = path.join(repositoryPath, candidate);
+        let content;
+        try {
+            if (fs.statSync(abs).size > MAX_FILE_SIZE_BYTES)
+                continue;
+            content = fs.readFileSync(abs, "utf8");
+        }
+        catch {
+            accepted.push(candidate);
+            continue;
+        }
+        if (importsIndexModule(candidate, content, file))
+            accepted.push(candidate);
+    }
+    return accepted;
+}
 /**
  * Checks each changed frontend file for a production importer — the
  * deterministic version of the grep the testbot prompt used to ask the

package/build/utils/importerHop.d.ts

@@ -1,3 +1,4 @@
+import { sliceAddedLinesByFile } from "./branchDiff.js";
 import type { ScannedEndpoint } from "./repoScanner.js";
 /**
  * Derives a singular, lowercase "resource token" from a backend source file
@@ -114,14 +115,7 @@ export declare function buildHopResponseShapeInputs(hopResult: ImporterHopResult
  * to be exhaustive.
  */
 export declare function extractFieldNamesFromAddedLines(lines: string[]): string[];
-/**
- * Splits a unified diff into per-file added-line arrays, keyed by the `b/`
- * (post-change) path. Exported so other file->resource-affinity callers
- * (e.g. `pathAffinityClassification.ts`'s fallback, SKYR-3857) can derive the
- * same per-file diff hunks this module uses for `deriveResourceTokensForFile`,
- * without re-implementing the diff-header walk.
- */
-export declare function sliceAddedLinesByFile(diffContent: string): Map<string, string[]>;
+export { sliceAddedLinesByFile };
 /**
  * Splits a unified diff into per-file raw sections — every line after a file's
  * `diff --git` header up to the next one — keyed by the `b/` (post-change) path.

package/build/utils/importerHop.js

@@ -56,8 +56,10 @@
 import * as fs from "fs";
 import * as path from "path";
 import { logger } from "./logger.js";
-import { extractResourceFromPath, isVersionLikeSegment, SKIP_PATH_SEGMENTS } from "./routeParsers.js";
-import { buildPathSignatures } from "./pathSignatures.js";
+import { extractResourceFromPath, isParamSegment, isVersionLikeSegment, SKIP_PATH_SEGMENTS } from "./routeParsers.js";
+import { sliceAddedLinesByFile } from "./branchDiff.js";
+import { buildPathSignatures, importsIndexModule, isIndexModule } from "./pathSignatures.js";
+import { singularize } from "./pluralization.js";
 import { isFrontendFile, isTestFile } from "../prompts/test-recommendation/scopeAssessment.js";
 const MAX_FILE_SIZE_BYTES = 512 * 1024;
 // Mirrors the small `SOURCE_EXTS` copies already living in routeParsers.ts and
@@ -165,19 +167,6 @@ function tokensFromSymbol(symbol) {
         !GENERIC_SYMBOL_TOKENS.has(token) &&
         !GENERIC_RESOURCE_TOKENS.has(token));
 }
-/**
- * Mirrors the private `singularize` in scenarioDrafting.ts (irregular-plural
- * rules for -ies/-ses/trailing-s). Duplicated rather than imported to avoid a
- * cross-module coupling for a 6-line pure function; keep the two in sync if
- * the pluralization rules ever change.
- */
-function singularize(word) {
-    if (word.endsWith("ies") && word.length > 3)
-        return word.slice(0, -3) + "y";
-    if (word.endsWith("ses") && word.length > 4)
-        return word.slice(0, -2);
-    return word.endsWith("s") && word.length > 1 ? word.slice(0, -1) : word;
-}
 /**
  * Derives a singular, lowercase "resource token" from a backend source file
  * path — e.g. "src/dtos/user.dto.ts" -> "user",
@@ -257,17 +246,6 @@ export function deriveResourceTokensForFile(file, diffHunk) {
     }
     return tokens.slice(0, MAX_RESOURCE_TOKENS);
 }
-// Mirrors the param-segment forms `isPathParam` in scenarioDrafting.ts
-// recognizes — OpenAPI-style "{id}", Express-style ":id", and Next.js-style
-// "[id]" / catch-all "[...id]" / optional catch-all "[[...id]]" (which needs
-// its own alternative: it contains an inner "]", so the single-bracket form's
-// [^\]]+ can never span it) — so the "primary" segment picked below never
-// lands on a parameter regardless of which framework's route syntax produced
-// the path.
-const PARAM_SEGMENT_RE = /^\{[^}]+\}$|^:[A-Za-z_]\w*$|^\[\[[^\]]+\]\]$|^\[[^\]]+\]$/;
-function isParamSegment(segment) {
-    return PARAM_SEGMENT_RE.test(segment);
-}
 /**
  * All singular resource tokens implied by an endpoint path, used for affinity
  * matching against a `deriveResourceToken` result. Shared by the importer-hop
@@ -353,9 +331,14 @@ export function mapUnmatchedFilesToImporterEndpoints(repositoryPath, unmatchedFi
             if (resourceTokens.length === 0)
                 continue;
             const signatures = buildPathSignatures(file);
+            // For an index module the directory stem is a plain string match, so also
+            // require the specifier to resolve to this module's directory.
+            const indexModule = isIndexModule(file);
             const rawCandidates = scannedEndpoints.filter((ep) => {
                 const content = readCached(ep.sourceFile);
-                return content !== null && signatures.some((sig) => content.includes(sig));
+                if (content === null || !signatures.some((sig) => content.includes(sig)))
+                    return false;
+                return !indexModule || importsIndexModule(ep.sourceFile, content, file);
             });
             if (rawCandidates.length === 0)
                 continue;
@@ -451,32 +434,11 @@ export function extractFieldNamesFromAddedLines(lines) {
     }
     return [...fields];
 }
-/**
- * Splits a unified diff into per-file added-line arrays, keyed by the `b/`
- * (post-change) path. Exported so other file->resource-affinity callers
- * (e.g. `pathAffinityClassification.ts`'s fallback, SKYR-3857) can derive the
- * same per-file diff hunks this module uses for `deriveResourceTokensForFile`,
- * without re-implementing the diff-header walk.
- */
-export function sliceAddedLinesByFile(diffContent) {
-    const sections = new Map();
-    let currentFile = null;
-    for (const line of diffContent.split("\n")) {
-        const headerMatch = /^diff --git a\/.+ b\/(.+)$/.exec(line);
-        if (headerMatch) {
-            currentFile = headerMatch[1];
-            continue;
-        }
-        if (!currentFile)
-            continue;
-        if (line.startsWith("+") && !line.startsWith("+++")) {
-            const arr = sections.get(currentFile) ?? [];
-            arr.push(line);
-            sections.set(currentFile, arr);
-        }
-    }
-    return sections;
-}
+// `sliceAddedLinesByFile` now lives in `branchDiff.ts` (imported above) — moved
+// there so modules this one already imports can reuse it without an import
+// cycle. Re-exported here so existing importers of it from this module
+// (pathAffinityClassification.ts) don't need to change their import path.
+export { sliceAddedLinesByFile };
 /**
  * Splits a unified diff into per-file raw sections — every line after a file's
  * `diff --git` header up to the next one — keyed by the `b/` (post-change) path.

package/build/utils/pathMatching.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Segment-aware path comparisons shared by endpoint/route matching across the
+ * codebase. Plain `startsWith`/`endsWith` are not sufficient for API paths:
+ * "/orders-archive".startsWith("/orders") and "/preorders".endsWith("orders")
+ * are both true even though the paths name different resources. These
+ * helpers require the match to land on a "/" (or path-end) boundary.
+ *
+ * Lives in its own module, independent of `routeParsers.ts` and
+ * `importerHop.ts`, so callers in either direction (`planRanker.ts` imports
+ * `routeParsers.ts`; `scenarioDrafting.ts` imports `importerHop.ts`, which
+ * imports `routeParsers.ts`) can both use it without risking an import cycle.
+ */
+/**
+ * Returns true when `a` starts with `b` at a path-segment boundary.
+ * Plain `startsWith` is not sufficient — "/orders-archive".startsWith("/orders") is true
+ * even though they are different resources. Requiring the next character to be "/" or
+ * end-of-string ensures only genuine path prefixes are matched.
+ */
+export declare const isSegmentPrefix: (a: string, b: string) => boolean;
+/**
+ * True when a path is nothing but a bare `id` parameter — `/:id`, `/{id}`.
+ *
+ * `canonicalSegment` unifies the SPELLING of a parameter, never its name, so
+ * `/{order_id}` still matches only a path ending in `{order_id}` — the name
+ * carries the resource and the match stays specific. A bare `id` carries
+ * nothing, so `/:id` ends `/api/users/{id}` and `/api/orders/{id}` alike. That
+ * is the shape a mounted Express router (`router.delete("/:id")`) and a NestJS
+ * handler (`@Delete(":id")`) declare, so it is common rather than exotic.
+ *
+ * Exported rather than folded into `pathSuffixMatches` because the two callers
+ * want opposite answers. `scenarioDrafting` resolves a router-relative path
+ * against the resource groups it knows, and its own test uses `/{order_id}` —
+ * a named parameter, which this predicate deliberately leaves alone.
+ * `planRanker` and subject resolution ask whether a diff line touches a given
+ * step, and there a bare `id` match is a false positive.
+ */
+export declare const isBareIdPath: (path: string) => boolean;
+export declare function pathSuffixMatches(fullPath: string, suffix: string): boolean;

package/build/utils/pathMatching.js

@@ -0,0 +1,71 @@
+/**
+ * Segment-aware path comparisons shared by endpoint/route matching across the
+ * codebase. Plain `startsWith`/`endsWith` are not sufficient for API paths:
+ * "/orders-archive".startsWith("/orders") and "/preorders".endsWith("orders")
+ * are both true even though the paths name different resources. These
+ * helpers require the match to land on a "/" (or path-end) boundary.
+ *
+ * Lives in its own module, independent of `routeParsers.ts` and
+ * `importerHop.ts`, so callers in either direction (`planRanker.ts` imports
+ * `routeParsers.ts`; `scenarioDrafting.ts` imports `importerHop.ts`, which
+ * imports `routeParsers.ts`) can both use it without risking an import cycle.
+ */
+/**
+ * Returns true when `a` starts with `b` at a path-segment boundary.
+ * Plain `startsWith` is not sufficient — "/orders-archive".startsWith("/orders") is true
+ * even though they are different resources. Requiring the next character to be "/" or
+ * end-of-string ensures only genuine path prefixes are matched.
+ */
+export const isSegmentPrefix = (a, b) => a.startsWith(b) && (a[b.length] === "/" || a[b.length] === undefined);
+/**
+ * One spelling for a route parameter. Express and NestJS declare a parameter as
+ * `:uid`, so that is what a diff line carries; OpenAPI and every candidate path
+ * write `{uid}`. The two name the same segment, so a comparison that reads them
+ * as different text rejects a genuine match — `/v2/org/{orgId}/members/{uid}`
+ * against a changed `@Delete("/members/:uid")` is the measured case.
+ *
+ * Only the spelling is unified, not the parameter NAME: on the recorded pairs
+ * the names always agree, and treating any parameter as a wildcard would let
+ * unrelated routes match.
+ */
+const canonicalSegment = (segment) => segment.startsWith(":") ? `{${segment.slice(1)}}` : segment;
+/**
+ * True when a path is nothing but a bare `id` parameter — `/:id`, `/{id}`.
+ *
+ * `canonicalSegment` unifies the SPELLING of a parameter, never its name, so
+ * `/{order_id}` still matches only a path ending in `{order_id}` — the name
+ * carries the resource and the match stays specific. A bare `id` carries
+ * nothing, so `/:id` ends `/api/users/{id}` and `/api/orders/{id}` alike. That
+ * is the shape a mounted Express router (`router.delete("/:id")`) and a NestJS
+ * handler (`@Delete(":id")`) declare, so it is common rather than exotic.
+ *
+ * Exported rather than folded into `pathSuffixMatches` because the two callers
+ * want opposite answers. `scenarioDrafting` resolves a router-relative path
+ * against the resource groups it knows, and its own test uses `/{order_id}` —
+ * a named parameter, which this predicate deliberately leaves alone.
+ * `planRanker` and subject resolution ask whether a diff line touches a given
+ * step, and there a bare `id` match is a false positive.
+ */
+export const isBareIdPath = (path) => {
+    const segs = path.split("/").filter(Boolean);
+    return (segs.length > 0 &&
+        segs.every((seg) => {
+            const canonical = canonicalSegment(seg);
+            return canonical.startsWith("{") && canonical.slice(1, -1).toLowerCase() === "id";
+        }));
+};
+// Segment-boundary suffix match: avoids "/orders" matching "/preorders".
+export function pathSuffixMatches(fullPath, suffix) {
+    if (fullPath === suffix)
+        return true;
+    const fullSegs = fullPath.split("/").filter(Boolean);
+    const suffixSegs = suffix.split("/").filter(Boolean);
+    if (suffixSegs.length === 0 || suffixSegs.length > fullSegs.length)
+        return false;
+    const offset = fullSegs.length - suffixSegs.length;
+    for (let i = 0; i < suffixSegs.length; i++) {
+        if (canonicalSegment(fullSegs[offset + i]) !== canonicalSegment(suffixSegs[i]))
+            return false;
+    }
+    return true;
+}

package/build/utils/pathSignatures.d.ts

@@ -1,6 +1,28 @@
 /**
  * Fixed-string signatures that identify an import of `file` by module path.
+ * For an `index.*` module the parent directory name is a stem too (`/Button'`).
  * Extensionless (`/Foo'`) covers TS/JS convention; extension-included
  * (`/Foo.vue'`) covers Vue/Svelte, where imports keep the extension.
  */
 export declare function buildPathSignatures(file: string): string[];
+/** True for `index.<ext>` modules, including `index.d.ts` (the same test buildPathSignatures uses). */
+export declare function isIndexModule(file: string): boolean;
+/**
+ * True when `importerContent` (the source of `importerFile`) contains an import
+ * specifier that targets the directory of `indexFile`. Companion to the
+ * parent-directory stem above: that stem is matched as a plain string, so
+ * `/_constants'` also hits a file importing its own, unrelated `./_constants`.
+ * Callers use this to keep only importers whose specifier targets this module.
+ *
+ * Specifier forms: `from '<spec>'`, `import '<spec>'` (side-effect), `import('<spec>')`,
+ * `require('<spec>')`. A trailing `/index` with any extension (`index.vue`,
+ * `index.d.ts`) is ignored, so extension-included imports (Vue/Svelte) match.
+ *
+ * Relative specifiers resolve against the importer's directory. Alias specifiers
+ * (`@/x`, `~/x`, `~~/x`, `#/x`, `src/x`) are accepted when the module directory
+ * ends with the aliased path AND the importer lives under the same root that the
+ * alias maps to — `packages/store/Page.tsx` importing `@/app/shop/_constants` does
+ * not match `packages/admin/app/shop/_constants/index.ts`. All paths are
+ * repo-relative with forward slashes.
+ */
+export declare function importsIndexModule(importerFile: string, importerContent: string, indexFile: string): boolean;

package/build/utils/pathSignatures.js

@@ -17,6 +17,7 @@
 import * as path from "path";
 /**
  * Fixed-string signatures that identify an import of `file` by module path.
+ * For an `index.*` module the parent directory name is a stem too (`/Button'`).
  * Extensionless (`/Foo'`) covers TS/JS convention; extension-included
  * (`/Foo.vue'`) covers Vue/Svelte, where imports keep the extension.
  */
@@ -29,5 +30,61 @@ export function buildPathSignatures(file) {
     const basename = isDts ? path.basename(file, ".d.ts") : path.basename(file, ext);
     const quotes = [`'`, `"`, "`"];
     const stems = [`/${basename}`, `/${basename}${ext}`];
+    // An index module is normally imported by its directory (`from './_constants'`,
+    // `from '@/components/Button'`); that import string never contains "index",
+    // so the basename stems alone miss every such importer.
+    if (isIndexModule(file)) {
+        const dir = path.basename(path.dirname(file));
+        if (dir && dir !== "." && dir !== "/")
+            stems.push(`/${dir}`);
+    }
     return stems.flatMap((stem) => quotes.map((q) => `${stem}${q}`));
 }
+/** True for `index.<ext>` modules, including `index.d.ts` (the same test buildPathSignatures uses). */
+export function isIndexModule(file) {
+    const isDts = /\.d\.ts$/i.test(file);
+    return (isDts ? path.basename(file, ".d.ts") : path.basename(file, path.extname(file))) === "index";
+}
+/**
+ * True when `importerContent` (the source of `importerFile`) contains an import
+ * specifier that targets the directory of `indexFile`. Companion to the
+ * parent-directory stem above: that stem is matched as a plain string, so
+ * `/_constants'` also hits a file importing its own, unrelated `./_constants`.
+ * Callers use this to keep only importers whose specifier targets this module.
+ *
+ * Specifier forms: `from '<spec>'`, `import '<spec>'` (side-effect), `import('<spec>')`,
+ * `require('<spec>')`. A trailing `/index` with any extension (`index.vue`,
+ * `index.d.ts`) is ignored, so extension-included imports (Vue/Svelte) match.
+ *
+ * Relative specifiers resolve against the importer's directory. Alias specifiers
+ * (`@/x`, `~/x`, `~~/x`, `#/x`, `src/x`) are accepted when the module directory
+ * ends with the aliased path AND the importer lives under the same root that the
+ * alias maps to — `packages/store/Page.tsx` importing `@/app/shop/_constants` does
+ * not match `packages/admin/app/shop/_constants/index.ts`. All paths are
+ * repo-relative with forward slashes.
+ */
+export function importsIndexModule(importerFile, importerContent, indexFile) {
+    const moduleDir = path.posix.dirname(indexFile.replace(/\\/g, "/"));
+    const importerPosix = importerFile.replace(/\\/g, "/");
+    const importerDir = path.posix.dirname(importerPosix);
+    const specRe = /(?:\bfrom\s*|\bimport\s*\(\s*|\brequire\s*\(\s*|\bimport\s+)(['"`])([^'"`]+)\1/g;
+    for (const m of importerContent.matchAll(specRe)) {
+        const spec = m[2].replace(/\/index(\.[\w]+)*$/, "").replace(/\/$/, "");
+        if (spec.startsWith(".")) {
+            if (path.posix.normalize(path.posix.join(importerDir, spec)) === moduleDir)
+                return true;
+            continue;
+        }
+        const aliased = spec.replace(/^(@\/|~~\/|~\/|#\/|src\/)/, "");
+        if (aliased === spec)
+            continue; // bare package specifier — not a repo path
+        if (moduleDir === aliased)
+            return true; // alias maps to the repo root
+        if (moduleDir.endsWith("/" + aliased)) {
+            const root = moduleDir.slice(0, -(aliased.length + 1));
+            if (importerPosix.startsWith(root + "/"))
+                return true;
+        }
+    }
+    return false;
+}

package/build/utils/planMatchKeys.d.ts

@@ -26,9 +26,22 @@ export interface PlanMatchQuery {
 /** Lowercase, collapse non-alphanumeric runs to '-', trim leading/trailing '-'. */
 export declare function slugifyName(name: string | undefined): string;
 /**
- * Normalize a path so param segments collapse: numeric ids, `{brace}` params,
- * `:colon` params, and long hex/uuid segments all become `:p`. Mirrors
- * discriminators.ts's normalizePath (duplicated here rather than imported —
+ * Normalize a path so param/id segments collapse: `{brace}`, `:colon`,
+ * `[bracket]` params in any of routeParsers.ts's syntaxes, plus numeric,
+ * UUID, and long-hex id VALUES, all become `:p`. Delegates to
+ * routeParsers.ts's `isParamSegment`/`isOpaqueIdSegment` (SKYR-4214 task 5)
+ * rather than a second inline copy — this module previously had its own
+ * looser hex rule (`/^[0-9a-fA-F-]{16,}$/`, accepting `-`) and no
+ * bracket-syntax rule at all, so a Next.js `[id]` segment never collapsed
+ * and kept a match key from matching its `{id}`-spelled counterpart (the
+ * SKYR-4123 failure mode: a generated test's key stops matching its plan
+ * item). The characterization test in
+ * `pathSegmentClassification.characterization.test.ts` confirms every
+ * previously-agreeing input (UUID, numeric, 16+/24-char hex) still
+ * collapses to `:p` after this change — safe within one run because the
+ * register-time key and the generation-time query are computed by the same
+ * build; a plan file is never persisted across builds. Mirrors
+ * discriminators.ts's normalizePath (duplicated rather than imported —
  * that function verifies discriminator claims against a diff, a different
  * concern from plan matching, and keeping them independent avoids coupling
  * this module's stability to phase 1's internal helper).