@hominis/fireforge 0.30.1 → 0.31.0

package/dist/src/core/patch-lint-jsdoc.js

@@ -37,13 +37,72 @@ function findAttachedJsDoc(comments, declStart, source) {
 // ---------------------------------------------------------------------------
 // JSDoc tag parsing
 // ---------------------------------------------------------------------------
+/**
+ * Skips a balanced `{ … }` JSDoc type expression starting at `start`
+ * (which must point at the opening brace). Braces nest in inline object
+ * types (`{{ id: string, args?: Record<string, boolean> }}`), so a flat
+ * "anything but `}`" regex truncates at the first inner close brace and
+ * loses the param name. String literal types may contain braces too, so
+ * quoted runs are skipped verbatim.
+ *
+ * @returns Index just past the matching close brace, or -1 when the type
+ *   expression never closes (malformed doc — caller skips the tag).
+ */
+function skipBalancedTypeBraces(jsDoc, start) {
+    let depth = 0;
+    let quote = null;
+    for (let i = start; i < jsDoc.length; i++) {
+        const ch = jsDoc[i];
+        if (quote !== null) {
+            if (ch === '\\')
+                i++;
+            else if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === "'" || ch === '"' || ch === '`') {
+            quote = ch;
+            continue;
+        }
+        if (ch === '{')
+            depth++;
+        else if (ch === '}') {
+            depth--;
+            if (depth === 0)
+                return i + 1;
+        }
+    }
+    return -1;
+}
 function extractParamNames(jsDoc) {
     const names = [];
-    const paramPattern = /@param\s+(?:\{[^}]*\}\s+)?(\w+)/g;
+    const tagPattern = /@param\b/g;
     let m;
-    while ((m = paramPattern.exec(jsDoc)) !== null) {
-        if (m[1])
-            names.push(m[1]);
+    while ((m = tagPattern.exec(jsDoc)) !== null) {
+        let i = m.index + m[0].length;
+        while (i < jsDoc.length && /\s/.test(jsDoc[i] ?? ''))
+            i++;
+        // Optional `{type}` expression — depth-aware so nested braces inside
+        // inline object types or Record<…> generics don't truncate the scan.
+        if (jsDoc[i] === '{') {
+            const afterType = skipBalancedTypeBraces(jsDoc, i);
+            if (afterType === -1)
+                continue;
+            i = afterType;
+            while (i < jsDoc.length && /\s/.test(jsDoc[i] ?? ''))
+                i++;
+        }
+        // Name token: bare `name`, optional `[name]`, or defaulted `[name=x]`.
+        // Dotted property docs (`opts.id`) record the base object name once.
+        const optional = jsDoc[i] === '[';
+        if (optional)
+            i++;
+        const nameMatch = /^[A-Za-z_$][\w$]*/.exec(jsDoc.slice(i));
+        if (!nameMatch)
+            continue;
+        const name = nameMatch[0];
+        if (!names.includes(name))
+            names.push(name);
     }
     return names;
 }

package/dist/src/core/patch-lint-observer.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `observer-topic-naming` rule body, extracted from `patch-lint.ts`.
+ *
+ * The historical implementation captured the first string literal after
+ * the call's opening paren on a single line. That mis-attributed string
+ * literals in complex subject arguments and silently skipped multi-line
+ * call sites. This version scans the balanced argument list (across
+ * newlines, string-aware), takes the *topic* argument by position, and
+ * allowlists well-known Firefox-owned topics so tests that simulate
+ * upstream notifications are not pushed toward renaming real topics.
+ */
+import type { PatchLintIssue } from '../types/commands/index.js';
+/**
+ * Firefox-owned observer topics a fork legitimately observes or simulates.
+ * These must never be flagged for fork-prefix naming, even when a fork's
+ * binaryName happens to be a substring of one. `quit-application*` is
+ * handled as a prefix family in {@link isKnownFirefoxTopic}.
+ *
+ * The list is deliberately conservative: it only needs to cover topics
+ * whose text could plausibly contain a fork's binaryName, plus the
+ * high-traffic lifecycle topics seen in downstream test simulations.
+ */
+export declare const KNOWN_FIREFOX_OBSERVER_TOPICS: ReadonlySet<string>;
+/** True for allowlisted Firefox topics, including the quit-application family. */
+export declare function isKnownFirefoxTopic(topic: string): boolean;
+/**
+ * Lints observer-service call sites in `strippedContent` (comments already
+ * removed) for fork topic naming. Only topics that embed `binaryName` and
+ * do not follow the `<binary>-<noun>-<verb>` convention are flagged;
+ * allowlisted Firefox topics and constant-named topics are skipped.
+ *
+ * @param strippedContent - Source with comments stripped
+ * @param file - File path for issue attribution
+ * @param binaryName - Lowercased fork binary name
+ * @returns Observer-topic naming issues
+ */
+export declare function lintObserverTopics(strippedContent: string, file: string, binaryName: string): PatchLintIssue[];

package/dist/src/core/patch-lint-observer.js

@@ -0,0 +1,168 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `observer-topic-naming` rule body, extracted from `patch-lint.ts`.
+ *
+ * The historical implementation captured the first string literal after
+ * the call's opening paren on a single line. That mis-attributed string
+ * literals in complex subject arguments and silently skipped multi-line
+ * call sites. This version scans the balanced argument list (across
+ * newlines, string-aware), takes the *topic* argument by position, and
+ * allowlists well-known Firefox-owned topics so tests that simulate
+ * upstream notifications are not pushed toward renaming real topics.
+ */
+/**
+ * Firefox-owned observer topics a fork legitimately observes or simulates.
+ * These must never be flagged for fork-prefix naming, even when a fork's
+ * binaryName happens to be a substring of one. `quit-application*` is
+ * handled as a prefix family in {@link isKnownFirefoxTopic}.
+ *
+ * The list is deliberately conservative: it only needs to cover topics
+ * whose text could plausibly contain a fork's binaryName, plus the
+ * high-traffic lifecycle topics seen in downstream test simulations.
+ */
+export const KNOWN_FIREFOX_OBSERVER_TOPICS = new Set([
+    'idle-daily',
+    'profile-after-change',
+    'profile-before-change',
+    'xpcom-shutdown',
+    'xpcom-will-shutdown',
+    'final-ui-startup',
+    'browser-delayed-startup-finished',
+    'sessionstore-windows-restored',
+    'document-element-inserted',
+    'content-document-global-created',
+    'http-on-modify-request',
+    'http-on-examine-response',
+    'nsPref:changed',
+    'browser-window-before-show',
+    'domwindowopened',
+    'domwindowclosed',
+]);
+/** True for allowlisted Firefox topics, including the quit-application family. */
+export function isKnownFirefoxTopic(topic) {
+    return KNOWN_FIREFOX_OBSERVER_TOPICS.has(topic) || topic.startsWith('quit-application');
+}
+/**
+ * Scans a balanced `( … )` argument span starting at `openParen` (which
+ * must point at the opening paren) and splits it into top-level argument
+ * strings. Tracks paren/brace/bracket depth and skips quoted runs, so
+ * commas inside nested calls, object literals, or strings do not split.
+ *
+ * @returns The argument texts, or null when the span never closes within
+ *   `maxLength` characters (malformed or truncated source — caller skips).
+ */
+function extractCallArguments(content, openParen, maxLength = 2000) {
+    const args = [];
+    let current = '';
+    let depth = 0;
+    let quote = null;
+    const end = Math.min(content.length, openParen + maxLength);
+    for (let i = openParen; i < end; i++) {
+        const ch = content[i] ?? '';
+        if (quote !== null) {
+            current += ch;
+            if (ch === '\\') {
+                current += content[i + 1] ?? '';
+                i++;
+            }
+            else if (ch === quote) {
+                quote = null;
+            }
+            continue;
+        }
+        if (ch === "'" || ch === '"' || ch === '`') {
+            quote = ch;
+            current += ch;
+            continue;
+        }
+        if (ch === '(' || ch === '{' || ch === '[') {
+            depth++;
+            if (depth === 1 && ch === '(')
+                continue; // the call's own paren
+            current += ch;
+            continue;
+        }
+        if (ch === ')' || ch === '}' || ch === ']') {
+            depth--;
+            if (depth === 0 && ch === ')') {
+                args.push(current.trim());
+                return args;
+            }
+            current += ch;
+            continue;
+        }
+        if (ch === ',' && depth === 1) {
+            args.push(current.trim());
+            current = '';
+            continue;
+        }
+        current += ch;
+    }
+    return null;
+}
+/**
+ * Returns the literal string value when `arg` is exactly one plain string
+ * literal (no concatenation, no `${}` interpolation), otherwise null.
+ * Constant-named topics (identifiers, member expressions) intentionally
+ * return null — hoisting a literal into a named constant is a supported
+ * way to mark a topic as deliberate.
+ */
+function asStringLiteral(arg) {
+    const trimmed = arg.trim();
+    if (trimmed.length < 2)
+        return null;
+    const quoteChar = trimmed[0];
+    if (quoteChar !== "'" && quoteChar !== '"' && quoteChar !== '`')
+        return null;
+    if (trimmed[trimmed.length - 1] !== quoteChar)
+        return null;
+    const inner = trimmed.slice(1, -1);
+    if (inner.includes(quoteChar))
+        return null; // concatenation like "a" + "b"
+    if (quoteChar === '`' && inner.includes('${'))
+        return null;
+    return inner;
+}
+/**
+ * Lints observer-service call sites in `strippedContent` (comments already
+ * removed) for fork topic naming. Only topics that embed `binaryName` and
+ * do not follow the `<binary>-<noun>-<verb>` convention are flagged;
+ * allowlisted Firefox topics and constant-named topics are skipped.
+ *
+ * @param strippedContent - Source with comments stripped
+ * @param file - File path for issue attribution
+ * @param binaryName - Lowercased fork binary name
+ * @returns Observer-topic naming issues
+ */
+export function lintObserverTopics(strippedContent, file, binaryName) {
+    const issues = [];
+    const callPattern = /\b(?:addObserver|removeObserver|notifyObservers)\s*\(/g;
+    let callMatch;
+    while ((callMatch = callPattern.exec(strippedContent)) !== null) {
+        const openParen = callMatch.index + callMatch[0].length - 1;
+        const args = extractCallArguments(strippedContent, openParen);
+        if (!args)
+            continue;
+        // Topic is the second argument for all three observer-service methods:
+        // addObserver(observer, topic[, weak]), removeObserver(observer, topic),
+        // notifyObservers(subject, topic[, data]).
+        const topicArg = args[1];
+        if (topicArg === undefined)
+            continue;
+        const topic = asStringLiteral(topicArg);
+        if (topic === null)
+            continue;
+        if (isKnownFirefoxTopic(topic))
+            continue;
+        if (topic.toLowerCase().includes(binaryName) && !/^[\w]+-[a-z]+-[a-z]+/.test(topic)) {
+            issues.push({
+                file,
+                check: 'observer-topic-naming',
+                message: `Observer topic "${topic}" should follow "${binaryName}-<noun>-<verb>" naming convention.`,
+                severity: 'warning',
+            });
+        }
+    }
+    return issues;
+}
+//# sourceMappingURL=patch-lint-observer.js.map

package/dist/src/core/patch-lint.js

@@ -12,6 +12,7 @@ import { detectNewFilesInDiff, extractAddedLinesPerFile } from './patch-lint-dif
 import { AGGREGATE_PATCH_FILE } from './patch-lint-diff-tag.js';
 import { hasRelativeImport } from './patch-lint-imports.js';
 import { validateExportJsDoc } from './patch-lint-jsdoc.js';
+import { lintObserverTopics } from './patch-lint-observer.js';
 import { resolvePatchOwnedChromeScripts, resolvePatchOwnedSysMjs } from './patch-lint-ownership.js';
 // ---------------------------------------------------------------------------
 // Cross-patch lint re-exports
@@ -204,9 +205,130 @@ export function commentStyleForFile(file) {
         return 'js';
     return null;
 }
-// ---------------------------------------------------------------------------
-// CSS lint
-// ---------------------------------------------------------------------------
+/**
+ * Loads the furnace token-prefix lint inputs gracefully — returns
+ * undefined (skipping the token-prefix check) when furnace.json cannot
+ * be loaded or no tokenPrefix is configured.
+ */
+async function loadCssTokenContext(repoDir) {
+    try {
+        const root = join(repoDir, '..');
+        const furnaceConfig = await loadFurnaceConfig(root);
+        if (furnaceConfig.tokenPrefix) {
+            return {
+                tokenPrefix: furnaceConfig.tokenPrefix,
+                tokenAllowlist: new Set(furnaceConfig.tokenAllowlist ?? []),
+                runtimeVariables: new Set(furnaceConfig.runtimeVariables ?? []),
+            };
+        }
+    }
+    catch (error) {
+        verbose(`Skipping furnace token-prefix lint hints because furnace.json could not be loaded: ${toError(error).message}`);
+    }
+    return undefined;
+}
+/**
+ * Raw-color check for one patched CSS file, scoped to introduced lines
+ * when diff context is available. Pushes onto `issues`.
+ */
+function checkRawColorValues(file, rawCss, addedLinesByFile, config, issues) {
+    // Check only introduced raw color values when diff context is available.
+    // Skip files on the raw-color allowlist (exact path or basename match) and
+    // auto-exempt files under `browser/branding/` — those are the fork's
+    // visual identity assets (app-about dialogs, installer pages, branded
+    // CSS copied from Firefox's `unofficial` template) and belong to the
+    // design-decision layer the design-token system does not govern.
+    // Without this auto-exemption, every first-time setup's copied CSS
+    // failed `raw-color-value` with no actionable fix other than manually
+    // listing each path in `rawColorAllowlist`.
+    const allowlist = config?.patchLint?.rawColorAllowlist;
+    const isAllowlisted = allowlist?.some((entry) => file === entry || file.endsWith('/' + entry));
+    const isBranding = file.startsWith('browser/branding/');
+    if (!isAllowlisted && !isBranding) {
+        // Strip lines with inline fireforge-ignore: raw-color-value suppression.
+        // Check against rawCss (before comment stripping) so the CSS comment marker is still present.
+        const sourceForSuppression = addedLinesByFile
+            ? (addedLinesByFile.get(file) ?? []).join('\n')
+            : rawCss;
+        const suppressedContent = sourceForSuppression
+            .split('\n')
+            .filter((line) => !line.includes('fireforge-ignore: raw-color-value'))
+            .join('\n')
+            .replace(/\/\*[\s\S]*?\*\//g, '');
+        if (hasRawCssColors(suppressedContent)) {
+            issues.push({
+                file,
+                check: 'raw-color-value',
+                message: 'Raw color value found. Use CSS custom properties (var(--...)) for design token consistency.',
+                severity: 'error',
+            });
+        }
+    }
+}
+/**
+ * Token-prefix check for one patched CSS file: flags `var(--x)` references
+ * that match neither the configured prefix, the allowlist, the runtime
+ * variables, nor a same-file declaration. Pushes onto `issues`.
+ */
+function checkTokenPrefixViolations(file, cssContent, addedLinesByFile, tokenContext, issues) {
+    // Check for non-tokenized custom properties. A variable that is both
+    // declared and consumed inside the same file is auto-exempted as a
+    // runtime state channel (see furnace.json → runtimeVariables).
+    //
+    // When diff context is available, scope the `var(...)` scan to
+    // added/modified lines only. `cssContent` (full-file) is still the
+    // source of `localDeclarations` so vars declared anywhere in the file
+    // are recognised as same-file refs regardless of where the consuming
+    // `var(...)` appears. Before this scoping change, a small edit to a
+    // Furnace override of a stock component (e.g. moz-card) produced a
+    // `token-prefix-violation` for every stock `var(--moz-card-*)` the
+    // upstream file already carried, because the scanner saw the full
+    // applied file and flagged each inherited reference as if the fork
+    // had introduced it.
+    if (tokenContext) {
+        const declarationPattern = /(?:^|[{;,\s])(--[\w-]+)\s*:/g;
+        const localDeclarations = new Set();
+        let declMatch;
+        while ((declMatch = declarationPattern.exec(cssContent)) !== null) {
+            const name = declMatch[1];
+            if (name)
+                localDeclarations.add(name);
+        }
+        const prefixScanSource = addedLinesByFile
+            ? (addedLinesByFile.get(file) ?? []).join('\n').replace(/\/\*[\s\S]*?\*\//g, '')
+            : cssContent;
+        if (prefixScanSource.length > 0) {
+            const varPattern = /var\(\s*(--[\w-]+)/g;
+            const flaggedProps = new Set();
+            let match;
+            while ((match = varPattern.exec(prefixScanSource)) !== null) {
+                const prop = match[1];
+                if (!prop)
+                    continue;
+                if (prop.startsWith(tokenContext.tokenPrefix))
+                    continue;
+                if (tokenContext.tokenAllowlist.has(prop))
+                    continue;
+                if (tokenContext.runtimeVariables.has(prop))
+                    continue;
+                if (localDeclarations.has(prop))
+                    continue;
+                // De-duplicate per (file, prop) pair so the same introduced var
+                // used five times in the added hunk doesn't produce five
+                // identical issue entries.
+                if (flaggedProps.has(prop))
+                    continue;
+                flaggedProps.add(prop);
+                issues.push({
+                    file,
+                    check: 'token-prefix-violation',
+                    message: `CSS references var(${prop}) which does not match the required token prefix "${tokenContext.tokenPrefix}". Use a design token, add to tokenAllowlist, or (for runtime state channels) list the variable in runtimeVariables.`,
+                    severity: 'error',
+                });
+            }
+        }
+    }
+}
 /**
  * Lints patched CSS files for introduced raw color values and non-tokenized
  * custom properties.
@@ -220,22 +342,7 @@ export async function lintPatchedCss(repoDir, affectedFiles, diffContent, config
     const cssFiles = affectedFiles.filter((f) => f.endsWith('.css'));
     if (cssFiles.length === 0)
         return [];
-    // Load furnace config gracefully — skip token-prefix check if unavailable
-    let tokenPrefix;
-    let tokenAllowlist;
-    let runtimeVariables;
-    try {
-        const root = join(repoDir, '..');
-        const furnaceConfig = await loadFurnaceConfig(root);
-        if (furnaceConfig.tokenPrefix) {
-            tokenPrefix = furnaceConfig.tokenPrefix;
-            tokenAllowlist = new Set(furnaceConfig.tokenAllowlist ?? []);
-            runtimeVariables = new Set(furnaceConfig.runtimeVariables ?? []);
-        }
-    }
-    catch (error) {
-        verbose(`Skipping furnace token-prefix lint hints because furnace.json could not be loaded: ${toError(error).message}`);
-    }
+    const tokenContext = await loadCssTokenContext(repoDir);
     const issues = [];
     const addedLinesByFile = diffContent ? extractAddedLinesPerFile(diffContent) : undefined;
     for (const file of cssFiles) {
@@ -245,95 +352,8 @@ export async function lintPatchedCss(repoDir, affectedFiles, diffContent, config
         const rawCss = await readText(filePath);
         // Strip block comments before scanning
         const cssContent = rawCss.replace(/\/\*[\s\S]*?\*\//g, '');
-        // Check only introduced raw color values when diff context is available.
-        // Skip files on the raw-color allowlist (exact path or basename match) and
-        // auto-exempt files under `browser/branding/` — those are the fork's
-        // visual identity assets (app-about dialogs, installer pages, branded
-        // CSS copied from Firefox's `unofficial` template) and belong to the
-        // design-decision layer the design-token system does not govern.
-        // Without this auto-exemption, every first-time setup's copied CSS
-        // failed `raw-color-value` with no actionable fix other than manually
-        // listing each path in `rawColorAllowlist`.
-        const allowlist = config?.patchLint?.rawColorAllowlist;
-        const isAllowlisted = allowlist?.some((entry) => file === entry || file.endsWith('/' + entry));
-        const isBranding = file.startsWith('browser/branding/');
-        if (!isAllowlisted && !isBranding) {
-            // Strip lines with inline fireforge-ignore: raw-color-value suppression.
-            // Check against rawCss (before comment stripping) so the CSS comment marker is still present.
-            const sourceForSuppression = addedLinesByFile
-                ? (addedLinesByFile.get(file) ?? []).join('\n')
-                : rawCss;
-            const suppressedContent = sourceForSuppression
-                .split('\n')
-                .filter((line) => !line.includes('fireforge-ignore: raw-color-value'))
-                .join('\n')
-                .replace(/\/\*[\s\S]*?\*\//g, '');
-            if (hasRawCssColors(suppressedContent)) {
-                issues.push({
-                    file,
-                    check: 'raw-color-value',
-                    message: 'Raw color value found. Use CSS custom properties (var(--...)) for design token consistency.',
-                    severity: 'error',
-                });
-            }
-        }
-        // Check for non-tokenized custom properties. A variable that is both
-        // declared and consumed inside the same file is auto-exempted as a
-        // runtime state channel (see furnace.json → runtimeVariables).
-        //
-        // When diff context is available, scope the `var(...)` scan to
-        // added/modified lines only. `cssContent` (full-file) is still the
-        // source of `localDeclarations` so vars declared anywhere in the file
-        // are recognised as same-file refs regardless of where the consuming
-        // `var(...)` appears. Before this scoping change, a small edit to a
-        // Furnace override of a stock component (e.g. moz-card) produced a
-        // `token-prefix-violation` for every stock `var(--moz-card-*)` the
-        // upstream file already carried, because the scanner saw the full
-        // applied file and flagged each inherited reference as if the fork
-        // had introduced it.
-        if (tokenPrefix) {
-            const declarationPattern = /(?:^|[{;,\s])(--[\w-]+)\s*:/g;
-            const localDeclarations = new Set();
-            let declMatch;
-            while ((declMatch = declarationPattern.exec(cssContent)) !== null) {
-                const name = declMatch[1];
-                if (name)
-                    localDeclarations.add(name);
-            }
-            const prefixScanSource = addedLinesByFile
-                ? (addedLinesByFile.get(file) ?? []).join('\n').replace(/\/\*[\s\S]*?\*\//g, '')
-                : cssContent;
-            if (prefixScanSource.length > 0) {
-                const varPattern = /var\(\s*(--[\w-]+)/g;
-                const flaggedProps = new Set();
-                let match;
-                while ((match = varPattern.exec(prefixScanSource)) !== null) {
-                    const prop = match[1];
-                    if (!prop)
-                        continue;
-                    if (prop.startsWith(tokenPrefix))
-                        continue;
-                    if (tokenAllowlist?.has(prop))
-                        continue;
-                    if (runtimeVariables?.has(prop))
-                        continue;
-                    if (localDeclarations.has(prop))
-                        continue;
-                    // De-duplicate per (file, prop) pair so the same introduced var
-                    // used five times in the added hunk doesn't produce five
-                    // identical issue entries.
-                    if (flaggedProps.has(prop))
-                        continue;
-                    flaggedProps.add(prop);
-                    issues.push({
-                        file,
-                        check: 'token-prefix-violation',
-                        message: `CSS references var(${prop}) which does not match the required token prefix "${tokenPrefix}". Use a design token, add to tokenAllowlist, or (for runtime state channels) list the variable in runtimeVariables.`,
-                        severity: 'error',
-                    });
-                }
-            }
-        }
+        checkRawColorValues(file, rawCss, addedLinesByFile, config, issues);
+        checkTokenPrefixViolations(file, cssContent, addedLinesByFile, tokenContext, issues);
     }
     return issues;
 }
@@ -503,23 +523,10 @@ export async function lintPatchedJs(repoDir, affectedFiles, newFiles, config, pa
                 });
             }
         }
-        // 4. Observer topic naming
-        const topicPattern = /(?:addObserver|removeObserver|notifyObservers)\s*\([^)\n]*["']([^"']+)["']/g;
-        let topicMatch;
-        while ((topicMatch = topicPattern.exec(strippedContent)) !== null) {
-            const topic = topicMatch[1];
-            if (!topic)
-                continue;
-            // Only flag topics that contain the binaryName but don't follow convention
-            if (topic.toLowerCase().includes(binaryName) && !/^[\w]+-[a-z]+-[a-z]+/.test(topic)) {
-                issues.push({
-                    file,
-                    check: 'observer-topic-naming',
-                    message: `Observer topic "${topic}" should follow "${binaryName}-<noun>-<verb>" naming convention.`,
-                    severity: 'warning',
-                });
-            }
-        }
+        // 4. Observer topic naming. Rule body lives in `patch-lint-observer.ts`:
+        // argument-position-aware, multi-line-safe, and allowlists Firefox-owned
+        // topics so simulated upstream notifications are not flagged.
+        issues.push(...lintObserverTopics(strippedContent, file, binaryName));
     }
     return issues;
 }

package/dist/src/core/patch-manifest-io.d.ts

@@ -85,6 +85,22 @@ export interface PatchRenameEntry {
     /** New numeric order — must match the prefix of `newFilename`. */
     newOrder: number;
 }
+/**
+ * Rewrites `stagedDependencies.forwardImports[].owner` references on one
+ * patch through a rename lookup. Owners embed exact patch filenames, so any
+ * renumber (compact, reorder, placement export, rename) that does not remap
+ * them leaves dangling references that surface as false forward-import
+ * errors on the next lint.
+ *
+ * Pure and allocation-conservative: returns the input object unchanged when
+ * no owner matches the lookup, so callers can map whole manifests cheaply.
+ *
+ * @param patch - Manifest row to rewrite
+ * @param renameLookup - Maps an old patch filename to its new filename, or
+ *   undefined when the filename is not being renamed
+ * @returns The same row, or a copy with remapped owners
+ */
+export declare function rewriteStagedDependencyOwners(patch: PatchMetadata, renameLookup: (oldFilename: string) => string | undefined): PatchMetadata;
 /**
  * Renames patch files on disk and rewrites the corresponding manifest rows
  * atomically-ish: file renames use a two-phase staging strategy (rename each

package/dist/src/core/patch-manifest-io.js

@@ -167,6 +167,44 @@ export async function removePatchFromManifest(patchesDir, filename) {
     await savePatchesManifest(patchesDir, manifest);
     return true;
 }
+/**
+ * Rewrites `stagedDependencies.forwardImports[].owner` references on one
+ * patch through a rename lookup. Owners embed exact patch filenames, so any
+ * renumber (compact, reorder, placement export, rename) that does not remap
+ * them leaves dangling references that surface as false forward-import
+ * errors on the next lint.
+ *
+ * Pure and allocation-conservative: returns the input object unchanged when
+ * no owner matches the lookup, so callers can map whole manifests cheaply.
+ *
+ * @param patch - Manifest row to rewrite
+ * @param renameLookup - Maps an old patch filename to its new filename, or
+ *   undefined when the filename is not being renamed
+ * @returns The same row, or a copy with remapped owners
+ */
+export function rewriteStagedDependencyOwners(patch, renameLookup) {
+    const forwardImports = patch.stagedDependencies?.forwardImports;
+    if (!forwardImports || forwardImports.length === 0)
+        return patch;
+    const rewritten = forwardImports.map((fi) => {
+        if (!fi.owner)
+            return fi;
+        const newOwner = renameLookup(fi.owner);
+        if (newOwner === undefined || newOwner === fi.owner)
+            return fi;
+        return { ...fi, owner: newOwner };
+    });
+    const changed = rewritten.some((fi, index) => fi !== forwardImports[index]);
+    if (!changed)
+        return patch;
+    return {
+        ...patch,
+        stagedDependencies: {
+            ...patch.stagedDependencies,
+            forwardImports: rewritten,
+        },
+    };
+}
 /**
  * Renames patch files on disk and rewrites the corresponding manifest rows
  * atomically-ish: file renames use a two-phase staging strategy (rename each
@@ -300,12 +338,16 @@ export async function renumberPatchesInManifest(patchesDir, renameMap) {
     for (const [oldFilename, entry] of renameMap) {
         filenameUpdates.set(oldFilename, entry);
     }
+    // Owner references live on *other* patches than the renamed ones, so every
+    // row is passed through the staged-dependency rewrite, not just renamed rows.
+    const ownerLookup = (oldFilename) => filenameUpdates.get(oldFilename)?.newFilename;
     const updatedPatches = manifest.patches.map((p) => {
         const update = filenameUpdates.get(p.filename);
+        const withOwners = rewriteStagedDependencyOwners(p, ownerLookup);
         if (!update)
-            return p;
+            return withOwners;
         return {
-            ...p,
+            ...withOwners,
             filename: update.newFilename,
             order: update.newOrder,
         };