@cellajs/cli 0.2.2 → 0.2.3

package/README.md

@@ -17,7 +17,7 @@ pnpm cella audit
 
 | Service | Description |
 |---------|-------------|
-| `analyze` | Dry run to see what would change on sync |
+| `analyze` | Dry run to see what would change on sync. It leaves your files and branches alone but updates git metadata: it fetches upstream and writes `refs/cella/last-sync` and a graft for the sync base |
 | `sync` | Merge upstream changes onto a fresh branch and open a squash-merge PR into `main` |
 | `audit` | Check for outdated packages & vulnerabilities |
 | `stats` | Count files by category and workspace package |
@@ -169,6 +169,36 @@ files with `· N upstream lines absent` (lines upstream has that the fork lacks,
 tips, `--json`: `upstreamLinesAbsent`). That is upstream content the fork never received,
 deliberately or not: diff and decide. Ignored files are not annotated.
 
+### Upstream changes that never sync
+
+Two more kinds of upstream change never reach the fork on their own. `analyze` prints both after
+its summary, and `sync` after its merge summary:
+
+- **Ignored paths changed upstream.** Upstream changed, added or deleted a file under an `ignored`
+  entry (app-owned module folders included) and the fork left it untouched. No conflict marks it,
+  so this is where new config keys and version bumps under `shared/config` show up. Each `ignored`
+  entry gets one line with a file count and a `git diff <last-sync>..<upstream> -- <entry>` line to
+  paste. Files both sides changed stay in the section above, and generated output the fork
+  regenerates itself (`sdk/gen`, `*.gen.*` files) is left out. `--list`/`--json` include these
+  files in `--scope all` and `--scope protected` (`--json`: `upstreamOnly`).
+- **Upstream override changes.** `cella/cella.config.ts` never syncs, so entries upstream adds to
+  its own `overrides.pinned` or `overrides.ignored` (the template your config started from) never
+  arrive. The report names each entry upstream added that your config lacks (`+`) and each entry
+  upstream dropped that your config still has (`−`). It reads upstream's config without running it
+  and never edits yours. `--json` puts the lists on the `cella/cella.config.ts` entry
+  (`upstreamOverrides`).
+
+```
+⚠ ignored paths changed upstream · 1 file under 1 entry
+  ⨂ frontend/src/modules/marketing · 1 file
+    git diff e9a8d485e..a81e3353b -- frontend/src/modules/marketing
+  the fork left these untouched and ignored paths never sync: diff and adopt what you need.
+
+⚠ upstream changed its sync overrides · 1 entry to review
+  + pinned: backend/src/bundle-config.ts
+  cella/cella.config.ts never syncs: add or drop these by hand where they fit your app.
+```
+
 ## Package.json sync
 
 `packageJsonSync` controls which package.json sections sync from upstream:

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/config/types.ts"],"sourcesContent":["/**\n * Sync CLI v2 - Configuration Types\n *\n * Simplified configuration for worktree-based merge approach.\n */\n\nimport { z } from 'zod';\n\n// ─────────────────────────────────────────────────────────────────────────────\n// PUBLIC API - for cella/cella.config.ts\n// ─────────────────────────────────────────────────────────────────────────────\n\n/** Valid package.json keys that can be synced */\nexport type PackageJsonSyncKey =\n  | 'dependencies'\n  | 'devDependencies'\n  | 'peerDependencies'\n  | 'optionalDependencies'\n  | 'scripts'\n  | 'engines'\n  | 'packageManager'\n  | 'overrides'\n  | 'exports'\n  | 'pnpm';\n\n/**\n * Sync settings - all configurable options for the sync CLI.\n * Hover over each property for documentation.\n */\nexport interface SyncSettings {\n  /** Upstream repository URL (e.g., 'git@github.com:cellajs/cella.git') */\n  upstreamUrl: string;\n\n  /**\n   * Upstream branch, used for `upstreamTrack: 'branch'` and for GitHub file links.\n   * Defaults to 'main'.\n   */\n  upstreamBranch?: string;\n\n  /**\n   * How to track upstream cella. Defaults to 'release'.\n   * - 'release' (default): sync to a published cella release tag (`v*`). Stable and\n   *   reviewable — each bump maps to a changelog. Uses the latest release.\n   * - 'branch': follow the bleeding-edge tip of `upstreamBranch`. For cella\n   *   maintainers and forks doing active development on top of unreleased changes.\n   */\n  upstreamTrack?: 'release' | 'branch';\n\n  /**\n   * Trunk branch that `pnpm cella sync` cuts the temporary branch from and that you open the\n   * squash-merge PR into. Defaults to 'main'. Cutting fresh from trunk each cycle keeps every\n   * PR limited to that cycle's upstream delta (no accumulation) and `main` linear.\n   */\n  releaseBase?: string;\n\n  /** Which package.json keys to sync (default: ['dependencies', 'devDependencies']) */\n  packageJsonSync?: PackageJsonSyncKey[];\n\n  /**\n   * Automatically run packages sync after the sync service completes.\n   * When true (default), the packages service is hidden from the menu\n   * and runs automatically as part of sync.\n   * Set to false to keep packages as a separate manual service.\n   */\n  syncWithPackages?: boolean;\n\n  /**\n   * How to link files in CLI output.\n   * - 'commit' (default): Link to the commit that changed the file on GitHub.\n   * - 'file': Link to the file in the repo at the upstream branch on GitHub.\n   * - 'local': Deprecated (the upstream view worktree was replaced by browser diffs); treated as 'file'.\n   */\n  fileLinkMode?: 'commit' | 'file' | 'local';\n}\n\n/**\n * Configuration for a downstream fork repository that cella interacts with.\n *\n * Cella is the upstream/source-of-truth. For each fork it can:\n * - pull contributions FROM the fork's `pullBranch` (contributions service)\n * - run the normal temporary-branch sync flow inside the fork (forks service)\n */\nexport interface ForkConfig {\n  /** Display name for the fork (also used as the contrib/<name> branch slug) */\n  name: string;\n  /** Local path to the fork repository (relative to this config or absolute) */\n  localPath: string;\n  /**\n   * Git remote URL of the fork (e.g. 'git@github.com:org/fork.git').\n   * When set, the contributions service fetches the fork's `pullBranch` from this\n   * remote (the authoritative committed ref) instead of the local clone, so the\n   * comparison no longer depends on the local checkout being up to date. The local\n   * clone is still used to read the fork's owned-folder territory when available.\n   */\n  remoteUrl?: string;\n  /** Fork branch that cella pulls contributions from (contributions service) */\n  pullBranch: string;\n}\n\n/**\n * User-configurable sync options for cella/cella.config.ts.\n * Simplified for v2 - no long-lived sync branch or squash options.\n */\nexport interface CellaCliConfig {\n  /** Core sync settings */\n  settings: SyncSettings;\n\n  /**\n   * File overrides for controlling sync behavior per folder/file.\n   */\n  overrides?: {\n    /**\n     * Paths the fork fully owns — never synced (existing or new).\n     * Exact paths or directory prefixes, not globs: 'bench' matches 'bench/' and\n     * everything under it, 'README.md' matches that exact file.\n     * Local territory: upstream cannot add, modify, or delete anything under these.\n     */\n    ignored?: string[];\n\n    /**\n     * Paths pinned to fork — fork wins on conflicts.\n     * Exact paths or directory prefixes, not globs: 'bench' matches 'bench/' and\n     * everything under it, 'README.md' matches that exact file.\n     * Non-conflicting upstream changes merge normally.\n     * If fork deleted a pinned file, deletion is respected.\n     */\n    pinned?: string[];\n  };\n\n  /**\n   * Downstream fork repositories that cella interacts with (for upstream template repos).\n   * When configured, the 'forks' and 'contributions' services appear in the CLI menu.\n   */\n  forks?: ForkConfig[];\n}\n\n/**\n * Helper function for defining cella/cella.config.ts with type checking.\n */\nexport function defineConfig(config: CellaCliConfig): CellaCliConfig {\n  return config;\n}\n\n/**\n * Strict runtime schema mirroring {@link CellaCliConfig}.\n *\n * The TS interfaces above stay the source of truth (and keep their hover docs for\n * config authors). This schema is what's enforced at load time: `.strict()` rejects\n * unknown keys, so a typo like `ignoredFolders` instead of `ignored` fails closed\n * instead of silently dropping sync protection (tsx does not typecheck the config).\n *\n * The `satisfies z.ZodType<CellaCliConfig>` assertion keeps schema and interface in\n * lockstep: if either drifts (a renamed/removed/mis-typed field), TypeScript errors here.\n */\nexport const cellaConfigSchema = z\n  .object({\n    settings: z\n      .object({\n        upstreamUrl: z.string().min(1),\n        upstreamBranch: z.string().min(1).optional(),\n        upstreamTrack: z.enum(['release', 'branch']).optional(),\n        releaseBase: z.string().min(1).optional(),\n        packageJsonSync: z\n          .array(\n            z.enum([\n              'dependencies',\n              'devDependencies',\n              'peerDependencies',\n              'optionalDependencies',\n              'scripts',\n              'engines',\n              'packageManager',\n              'overrides',\n              'exports',\n              'pnpm',\n            ]),\n          )\n          .optional(),\n        syncWithPackages: z.boolean().optional(),\n        fileLinkMode: z.enum(['commit', 'file', 'local']).optional(),\n      })\n      .strict(),\n    overrides: z\n      .object({\n        ignored: z.array(z.string()).optional(),\n        pinned: z.array(z.string()).optional(),\n      })\n      .strict()\n      .optional(),\n    forks: z\n      .array(\n        z\n          .object({\n            name: z.string().min(1),\n            localPath: z.string().min(1),\n            remoteUrl: z.string().optional(),\n            pullBranch: z.string().min(1),\n          })\n          .strict(),\n      )\n      .optional(),\n  })\n  .strict() satisfies z.ZodType<CellaCliConfig>;\n\n// ─────────────────────────────────────────────────────────────────────────────\n// INTERNAL TYPES - for sync modules\n// ─────────────────────────────────────────────────────────────────────────────\n\n/** Sync services available in the CLI */\nexport type SyncService = 'analyze' | 'sync' | 'audit' | 'forks' | 'contributions' | 'stats';\n\n/** Analyze output scope for interactive and machine-readable flows */\nexport type AnalyzeScope = 'all' | 'risk' | 'protected';\n\n/** Runtime configuration with all resolved values */\nexport interface RuntimeConfig extends CellaCliConfig {\n  /** Resolved fork repository path */\n  forkPath: string;\n\n  /** Full upstream remote ref (e.g., 'cella-upstream/development') */\n  upstreamRef: string;\n\n  /** Selected sync service */\n  service: SyncService;\n\n  /** Write full file list to log file */\n  logFile: boolean;\n\n  /** Non-interactive list output (for LLM/agent usage) */\n  list: boolean;\n\n  /** Machine-readable JSON output (for tooling/agent usage) */\n  json: boolean;\n\n  /** Print the unified diff for a single contributed file, then exit (contributions; for tooling/agents) */\n  diff?: string;\n\n  /** Open a browser diff for one file, then exit (analyze) */\n  openDiff?: string;\n\n  /** Scope of files returned in analyze list/json output */\n  scope?: AnalyzeScope;\n\n  /** Show verbose output */\n  verbose: boolean;\n\n  /** Pre-selected fork name (skips fork selection prompt) */\n  fork?: string;\n\n  /** Overwrite drifted files with upstream version (aggressive realignment) */\n  hard?: boolean;\n\n  /**\n   * Disable pinned entries (cella/cella.config.ts overrides.pinned) for this sync so upstream\n   * versions surface as behind/diverged. Managed files stay pinned because cella\n   * handles them separately. Like --hard, uses the natural merge-base to resurface\n   * full upstream history.\n   */\n  unpinned?: boolean;\n\n  /**\n   * Override upstream tracking for this run (analyze/sync), ignoring `settings.upstreamTrack`.\n   * 'branch' follows the upstream branch tip (bleeding edge); 'release' uses a release tag.\n   */\n  track?: 'release' | 'branch';\n\n  /** Bypass pnpm metadata cache for fresh registry data (audit service) */\n  force?: boolean;\n\n  /** Check which pnpm.overrides are still needed (audit service) */\n  checkOverrides?: boolean;\n\n  /** Regenerate test coverage before showing the stats summary (stats service) */\n  coverage?: boolean;\n\n  /**\n   * After opening the sync PR, enable GitHub auto-merge (squash) so it merges itself once\n   * required checks pass (sync service). Opt-in per run via `--direct-merge`; needs auto-merge\n   * enabled on the repo. Not the advised default — a sync PR is usually worth a human look.\n   */\n  directMerge?: boolean;\n}\n\n/** File status after analysis */\nexport type FileStatus =\n  | 'identical' // No changes needed\n  | 'ahead' // Fork is ahead, protected (pinned/ignored)\n  | 'local' // Local file (never existed upstream)\n  | 'drifted' // Fork is ahead, NOT protected (at risk)\n  | 'behind' // Upstream has changes to sync\n  | 'diverged' // Both changed, will merge\n  | 'pinned' // Fork wins on conflict\n  | 'ignored' // Excluded from sync entirely\n  | 'deleted' // Fork deleted, will stay deleted\n  | 'renamed'; // Upstream renamed file\n\n/** Analyzed file with status and metadata */\nexport interface AnalyzedFile {\n  path: string;\n  status: FileStatus;\n  /** True if file is in ignored list */\n  isIgnored: boolean;\n  /** True if file is in pinned list */\n  isPinned: boolean;\n  /** True if file exists in fork */\n  existsInFork: boolean;\n  /** True if file exists in upstream */\n  existsInUpstream: boolean;\n  /** True if file has merge conflict */\n  hasConflict?: boolean;\n  /** Relative date when file was last changed (since merge-base) */\n  changedAt?: string;\n  /** Unix epoch seconds of the last change, for sorting */\n  changedTs?: number;\n  /** Short commit hash of the last change */\n  changedCommit?: string;\n  /** For diverged files: relative date of upstream change */\n  upstreamChangedAt?: string;\n  /** For diverged files: Unix epoch seconds of the upstream change, for sorting */\n  upstreamChangedTs?: number;\n  /** For diverged files: short commit hash of the upstream change */\n  upstreamCommit?: string;\n  /** For renamed files: the original path before rename */\n  renamedFrom?: string;\n  /**\n   * Protected (pinned/ignored) files only: both sides changed since the merge-base. The fork\n   * side wins whole-file, so upstream's changes to this path are dropped by the sync.\n   */\n  upstreamChanged?: boolean;\n  /** For `upstreamChanged` files: lines upstream changed since the merge-base (undefined for binary) */\n  upstreamChangedLines?: number;\n  /**\n   * Pinned `ahead` files only: lines present upstream but absent from the fork (undefined for\n   * binary). Independent of the sync point, so it also shows upstream content dropped by an\n   * earlier sync — or removed on purpose; only a diff can tell.\n   */\n  upstreamLinesAbsent?: number;\n}\n\n/** Summary counts by status */\nexport interface AnalysisSummary {\n  /** Changed package/config files that are handled separately from normal sync categories */\n  managed: number;\n  identical: number;\n  ahead: number;\n  local: number;\n  drifted: number;\n  behind: number;\n  diverged: number;\n  pinned: number;\n  ignored: number;\n  deleted: number;\n  renamed: number;\n  total: number;\n}\n\n/** Merge result from merge-engine */\nexport interface MergeResult {\n  success: boolean;\n  /** Upstream branch name for file links */\n  upstreamBranch?: string;\n  /** Resolved concrete upstream ref that was merged (branch ref or release tag ref) */\n  upstreamRef?: string;\n  /** Upstream release tag synced (when tracking releases) */\n  upstreamTag?: string;\n  files: AnalyzedFile[];\n  summary: AnalysisSummary;\n  conflicts: string[];\n  /** Upstream GitHub URL base for commit links */\n  upstreamGitHubUrl?: string;\n  /** Upstream commit info */\n  upstreamCommit?: {\n    hash: string;\n    message: string;\n    date: string;\n  };\n  /** Commits included in this sync range (oldest-first when rendered) */\n  upstreamCommits?: Array<{\n    hash: string;\n    message: string;\n    date: string;\n  }>;\n  /** Files that were auto-merged by git (diverged without remaining conflicts) */\n  autoMergedFiles?: string[];\n  /**\n   * Protected (pinned/ignored) files resolved to the fork side although upstream also changed\n   * them: upstream's hunks were dropped, not merged. Review each against upstream.\n   */\n  protectedConflicts?: string[];\n}\n"],"mappings":";AAMA,SAAS,SAAS;AAqIX,SAAS,aAAa,QAAwC;AACnE,SAAO;AACT;AAaO,IAAM,oBAAoB,EAC9B,OAAO;AAAA,EACN,UAAU,EACP,OAAO;AAAA,IACN,aAAa,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,IAC7B,gBAAgB,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,SAAS;AAAA,IAC3C,eAAe,EAAE,KAAK,CAAC,WAAW,QAAQ,CAAC,EAAE,SAAS;AAAA,IACtD,aAAa,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,SAAS;AAAA,IACxC,iBAAiB,EACd;AAAA,MACC,EAAE,KAAK;AAAA,QACL;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,MACF,CAAC;AAAA,IACH,EACC,SAAS;AAAA,IACZ,kBAAkB,EAAE,QAAQ,EAAE,SAAS;AAAA,IACvC,cAAc,EAAE,KAAK,CAAC,UAAU,QAAQ,OAAO,CAAC,EAAE,SAAS;AAAA,EAC7D,CAAC,EACA,OAAO;AAAA,EACV,WAAW,EACR,OAAO;AAAA,IACN,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS;AAAA,IACtC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS;AAAA,EACvC,CAAC,EACA,OAAO,EACP,SAAS;AAAA,EACZ,OAAO,EACJ;AAAA,IACC,EACG,OAAO;AAAA,MACN,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,MACtB,WAAW,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,MAC3B,WAAW,EAAE,OAAO,EAAE,SAAS;AAAA,MAC/B,YAAY,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,IAC9B,CAAC,EACA,OAAO;AAAA,EACZ,EACC,SAAS;AACd,CAAC,EACA,OAAO;","names":[]}
+{"version":3,"sources":["../src/config/types.ts"],"sourcesContent":["/**\n * Sync CLI v2 - Configuration Types\n *\n * Simplified configuration for worktree-based merge approach.\n */\n\nimport { z } from 'zod';\n\n// ─────────────────────────────────────────────────────────────────────────────\n// PUBLIC API - for cella/cella.config.ts\n// ─────────────────────────────────────────────────────────────────────────────\n\n/** Valid package.json keys that can be synced */\nexport type PackageJsonSyncKey =\n  | 'dependencies'\n  | 'devDependencies'\n  | 'peerDependencies'\n  | 'optionalDependencies'\n  | 'scripts'\n  | 'engines'\n  | 'packageManager'\n  | 'overrides'\n  | 'exports'\n  | 'pnpm';\n\n/**\n * Sync settings - all configurable options for the sync CLI.\n * Hover over each property for documentation.\n */\nexport interface SyncSettings {\n  /** Upstream repository URL (e.g., 'git@github.com:cellajs/cella.git') */\n  upstreamUrl: string;\n\n  /**\n   * Upstream branch, used for `upstreamTrack: 'branch'` and for GitHub file links.\n   * Defaults to 'main'.\n   */\n  upstreamBranch?: string;\n\n  /**\n   * How to track upstream cella. Defaults to 'release'.\n   * - 'release' (default): sync to a published cella release tag (`v*`). Stable and\n   *   reviewable — each bump maps to a changelog. Uses the latest release.\n   * - 'branch': follow the bleeding-edge tip of `upstreamBranch`. For cella\n   *   maintainers and forks doing active development on top of unreleased changes.\n   */\n  upstreamTrack?: 'release' | 'branch';\n\n  /**\n   * Trunk branch that `pnpm cella sync` cuts the temporary branch from and that you open the\n   * squash-merge PR into. Defaults to 'main'. Cutting fresh from trunk each cycle keeps every\n   * PR limited to that cycle's upstream delta (no accumulation) and `main` linear.\n   */\n  releaseBase?: string;\n\n  /** Which package.json keys to sync (default: ['dependencies', 'devDependencies']) */\n  packageJsonSync?: PackageJsonSyncKey[];\n\n  /**\n   * Automatically run packages sync after the sync service completes.\n   * When true (default), the packages service is hidden from the menu\n   * and runs automatically as part of sync.\n   * Set to false to keep packages as a separate manual service.\n   */\n  syncWithPackages?: boolean;\n\n  /**\n   * How to link files in CLI output.\n   * - 'commit' (default): Link to the commit that changed the file on GitHub.\n   * - 'file': Link to the file in the repo at the upstream branch on GitHub.\n   * - 'local': Deprecated (the upstream view worktree was replaced by browser diffs); treated as 'file'.\n   */\n  fileLinkMode?: 'commit' | 'file' | 'local';\n}\n\n/**\n * Configuration for a downstream fork repository that cella interacts with.\n *\n * Cella is the upstream/source-of-truth. For each fork it can:\n * - pull contributions FROM the fork's `pullBranch` (contributions service)\n * - run the normal temporary-branch sync flow inside the fork (forks service)\n */\nexport interface ForkConfig {\n  /** Display name for the fork (also used as the contrib/<name> branch slug) */\n  name: string;\n  /** Local path to the fork repository (relative to this config or absolute) */\n  localPath: string;\n  /**\n   * Git remote URL of the fork (e.g. 'git@github.com:org/fork.git').\n   * When set, the contributions service fetches the fork's `pullBranch` from this\n   * remote (the authoritative committed ref) instead of the local clone, so the\n   * comparison no longer depends on the local checkout being up to date. The local\n   * clone is still used to read the fork's owned-folder territory when available.\n   */\n  remoteUrl?: string;\n  /** Fork branch that cella pulls contributions from (contributions service) */\n  pullBranch: string;\n}\n\n/**\n * User-configurable sync options for cella/cella.config.ts.\n * Simplified for v2 - no long-lived sync branch or squash options.\n */\nexport interface CellaCliConfig {\n  /** Core sync settings */\n  settings: SyncSettings;\n\n  /**\n   * File overrides for controlling sync behavior per folder/file.\n   */\n  overrides?: {\n    /**\n     * Paths the fork fully owns — never synced (existing or new).\n     * Exact paths or directory prefixes, not globs: 'bench' matches 'bench/' and\n     * everything under it, 'README.md' matches that exact file.\n     * Local territory: upstream cannot add, modify, or delete anything under these.\n     */\n    ignored?: string[];\n\n    /**\n     * Paths pinned to fork — fork wins on conflicts.\n     * Exact paths or directory prefixes, not globs: 'bench' matches 'bench/' and\n     * everything under it, 'README.md' matches that exact file.\n     * Non-conflicting upstream changes merge normally.\n     * If fork deleted a pinned file, deletion is respected.\n     */\n    pinned?: string[];\n  };\n\n  /**\n   * Downstream fork repositories that cella interacts with (for upstream template repos).\n   * When configured, the 'forks' and 'contributions' services appear in the CLI menu.\n   */\n  forks?: ForkConfig[];\n}\n\n/**\n * Helper function for defining cella/cella.config.ts with type checking.\n */\nexport function defineConfig(config: CellaCliConfig): CellaCliConfig {\n  return config;\n}\n\n/**\n * Strict runtime schema mirroring {@link CellaCliConfig}.\n *\n * The TS interfaces above stay the source of truth (and keep their hover docs for\n * config authors). This schema is what's enforced at load time: `.strict()` rejects\n * unknown keys, so a typo like `ignoredFolders` instead of `ignored` fails closed\n * instead of silently dropping sync protection (tsx does not typecheck the config).\n *\n * The `satisfies z.ZodType<CellaCliConfig>` assertion keeps schema and interface in\n * lockstep: if either drifts (a renamed/removed/mis-typed field), TypeScript errors here.\n */\nexport const cellaConfigSchema = z\n  .object({\n    settings: z\n      .object({\n        upstreamUrl: z.string().min(1),\n        upstreamBranch: z.string().min(1).optional(),\n        upstreamTrack: z.enum(['release', 'branch']).optional(),\n        releaseBase: z.string().min(1).optional(),\n        packageJsonSync: z\n          .array(\n            z.enum([\n              'dependencies',\n              'devDependencies',\n              'peerDependencies',\n              'optionalDependencies',\n              'scripts',\n              'engines',\n              'packageManager',\n              'overrides',\n              'exports',\n              'pnpm',\n            ]),\n          )\n          .optional(),\n        syncWithPackages: z.boolean().optional(),\n        fileLinkMode: z.enum(['commit', 'file', 'local']).optional(),\n      })\n      .strict(),\n    overrides: z\n      .object({\n        ignored: z.array(z.string()).optional(),\n        pinned: z.array(z.string()).optional(),\n      })\n      .strict()\n      .optional(),\n    forks: z\n      .array(\n        z\n          .object({\n            name: z.string().min(1),\n            localPath: z.string().min(1),\n            remoteUrl: z.string().optional(),\n            pullBranch: z.string().min(1),\n          })\n          .strict(),\n      )\n      .optional(),\n  })\n  .strict() satisfies z.ZodType<CellaCliConfig>;\n\n// ─────────────────────────────────────────────────────────────────────────────\n// INTERNAL TYPES - for sync modules\n// ─────────────────────────────────────────────────────────────────────────────\n\n/** Sync services available in the CLI */\nexport type SyncService = 'analyze' | 'sync' | 'audit' | 'forks' | 'contributions' | 'stats';\n\n/** Analyze output scope for interactive and machine-readable flows */\nexport type AnalyzeScope = 'all' | 'risk' | 'protected';\n\n/** Runtime configuration with all resolved values */\nexport interface RuntimeConfig extends CellaCliConfig {\n  /** Resolved fork repository path */\n  forkPath: string;\n\n  /** Full upstream remote ref (e.g., 'cella-upstream/development') */\n  upstreamRef: string;\n\n  /** Selected sync service */\n  service: SyncService;\n\n  /** Write full file list to log file */\n  logFile: boolean;\n\n  /** Non-interactive list output (for LLM/agent usage) */\n  list: boolean;\n\n  /** Machine-readable JSON output (for tooling/agent usage) */\n  json: boolean;\n\n  /** Print the unified diff for a single contributed file, then exit (contributions; for tooling/agents) */\n  diff?: string;\n\n  /** Open a browser diff for one file, then exit (analyze) */\n  openDiff?: string;\n\n  /** Scope of files returned in analyze list/json output */\n  scope?: AnalyzeScope;\n\n  /** Show verbose output */\n  verbose: boolean;\n\n  /** Pre-selected fork name (skips fork selection prompt) */\n  fork?: string;\n\n  /** Overwrite drifted files with upstream version (aggressive realignment) */\n  hard?: boolean;\n\n  /**\n   * Disable pinned entries (cella/cella.config.ts overrides.pinned) for this sync so upstream\n   * versions surface as behind/diverged. Managed files stay pinned because cella\n   * handles them separately. Like --hard, uses the natural merge-base to resurface\n   * full upstream history.\n   */\n  unpinned?: boolean;\n\n  /**\n   * Override upstream tracking for this run (analyze/sync), ignoring `settings.upstreamTrack`.\n   * 'branch' follows the upstream branch tip (bleeding edge); 'release' uses a release tag.\n   */\n  track?: 'release' | 'branch';\n\n  /** Bypass pnpm metadata cache for fresh registry data (audit service) */\n  force?: boolean;\n\n  /** Check which pnpm.overrides are still needed (audit service) */\n  checkOverrides?: boolean;\n\n  /** Regenerate test coverage before showing the stats summary (stats service) */\n  coverage?: boolean;\n\n  /**\n   * After opening the sync PR, enable GitHub auto-merge (squash) so it merges itself once\n   * required checks pass (sync service). Opt-in per run via `--direct-merge`; needs auto-merge\n   * enabled on the repo. Not the advised default — a sync PR is usually worth a human look.\n   */\n  directMerge?: boolean;\n}\n\n/** File status after analysis */\nexport type FileStatus =\n  | 'identical' // No changes needed\n  | 'ahead' // Fork is ahead, protected (pinned/ignored)\n  | 'local' // Local file (never existed upstream)\n  | 'drifted' // Fork is ahead, NOT protected (at risk)\n  | 'behind' // Upstream has changes to sync\n  | 'diverged' // Both changed, will merge\n  | 'pinned' // Fork wins on conflict\n  | 'ignored' // Excluded from sync entirely\n  | 'deleted' // Fork deleted, will stay deleted\n  | 'renamed'; // Upstream renamed file\n\n/** Analyzed file with status and metadata */\nexport interface AnalyzedFile {\n  path: string;\n  status: FileStatus;\n  /** True if file is in ignored list */\n  isIgnored: boolean;\n  /** True if file is in pinned list */\n  isPinned: boolean;\n  /** True if file exists in fork */\n  existsInFork: boolean;\n  /** True if file exists in upstream */\n  existsInUpstream: boolean;\n  /** True if file has merge conflict */\n  hasConflict?: boolean;\n  /** Relative date when file was last changed (since merge-base) */\n  changedAt?: string;\n  /** Unix epoch seconds of the last change, for sorting */\n  changedTs?: number;\n  /** Short commit hash of the last change */\n  changedCommit?: string;\n  /** For diverged files: relative date of upstream change */\n  upstreamChangedAt?: string;\n  /** For diverged files: Unix epoch seconds of the upstream change, for sorting */\n  upstreamChangedTs?: number;\n  /** For diverged files: short commit hash of the upstream change */\n  upstreamCommit?: string;\n  /** For renamed files: the original path before rename */\n  renamedFrom?: string;\n  /**\n   * Protected (pinned/ignored) files only: both sides changed since the merge-base. The fork\n   * side wins whole-file, so upstream's changes to this path are dropped by the sync.\n   */\n  upstreamChanged?: boolean;\n  /** For `upstreamChanged` files: lines upstream changed since the merge-base (undefined for binary) */\n  upstreamChangedLines?: number;\n  /**\n   * Ignored files only: upstream changed, added or deleted the file since the merge-base and the\n   * fork did not touch it. Ignored paths never sync, so without this flag the change stays unseen\n   * (new config keys, version bumps). Managed files and generated output (`isGeneratedFile`) are\n   * never flagged.\n   */\n  upstreamOnly?: boolean;\n  /**\n   * Pinned `ahead` files only: lines present upstream but absent from the fork (undefined for\n   * binary). Independent of the sync point, so it also shows upstream content dropped by an\n   * earlier sync — or removed on purpose; only a diff can tell.\n   */\n  upstreamLinesAbsent?: number;\n}\n\n/** Summary counts by status */\nexport interface AnalysisSummary {\n  /** Changed package/config files that are handled separately from normal sync categories */\n  managed: number;\n  identical: number;\n  ahead: number;\n  local: number;\n  drifted: number;\n  behind: number;\n  diverged: number;\n  pinned: number;\n  ignored: number;\n  deleted: number;\n  renamed: number;\n  total: number;\n}\n\n/** Merge result from merge-engine */\nexport interface MergeResult {\n  success: boolean;\n  /** Upstream branch name for file links */\n  upstreamBranch?: string;\n  /** Resolved concrete upstream ref that was merged (branch ref or release tag ref) */\n  upstreamRef?: string;\n  /** Upstream release tag synced (when tracking releases) */\n  upstreamTag?: string;\n  files: AnalyzedFile[];\n  summary: AnalysisSummary;\n  conflicts: string[];\n  /** Upstream GitHub URL base for commit links */\n  upstreamGitHubUrl?: string;\n  /** Upstream commit info */\n  upstreamCommit?: {\n    hash: string;\n    message: string;\n    date: string;\n  };\n  /** Commits included in this sync range (oldest-first when rendered) */\n  upstreamCommits?: Array<{\n    hash: string;\n    message: string;\n    date: string;\n  }>;\n  /** Files that were auto-merged by git (diverged without remaining conflicts) */\n  autoMergedFiles?: string[];\n  /**\n   * Protected (pinned/ignored) files resolved to the fork side although upstream also changed\n   * them: upstream's hunks were dropped, not merged. Review each against upstream.\n   */\n  protectedConflicts?: string[];\n  /** Pasteable `<merge-base>..<upstream>` range of short SHAs, for `git diff` hints. */\n  upstreamDiffRange?: string;\n  /** How upstream's own `overrides` changed since the merge-base, where the fork config does not follow. */\n  upstreamOverrides?: UpstreamOverridesReport;\n  /** Files flagged `upstreamOnly`, grouped by the `ignored` entry they fall under (config order). */\n  ignoredUpstreamChanges?: IgnoredUpstreamGroup[];\n}\n\n/** Entries of one override list (`pinned` or `ignored`) that the fork config does not mirror. */\nexport interface OverrideListChanges {\n  /** Entries upstream added since the merge-base that the fork list lacks. */\n  added: string[];\n  /** Entries upstream removed since the merge-base that the fork list still carries. */\n  removed: string[];\n}\n\n/**\n * Upstream override changes the fork should review. The sync config is managed (never merged),\n * so new upstream `pinned`/`ignored` entries only reach the fork by hand. `unreadable` means\n * upstream's config was missing or unparsable at one side (`base` = merge-base, `incoming` =\n * upstream ref), so nothing was compared.\n */\nexport type UpstreamOverridesReport =\n  | { kind: 'changes'; pinned: OverrideListChanges; ignored: OverrideListChanges }\n  | { kind: 'unreadable'; side: 'base' | 'incoming' };\n\n/** Upstream-only changes under one `ignored` entry. */\nexport interface IgnoredUpstreamGroup {\n  /** The `ignored` entry (configured or derived from an app-owned module) the files fall under. */\n  entry: string;\n  /** Changed paths under the entry, sorted. */\n  paths: string[];\n  /** Paths the fork lacks (new upstream files). */\n  added: number;\n  /** Paths upstream deleted (the fork keeps them). */\n  deleted: number;\n}\n"],"mappings":";AAMA,SAAS,SAAS;AAqIX,SAAS,aAAa,QAAwC;AACnE,SAAO;AACT;AAaO,IAAM,oBAAoB,EAC9B,OAAO;AAAA,EACN,UAAU,EACP,OAAO;AAAA,IACN,aAAa,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,IAC7B,gBAAgB,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,SAAS;AAAA,IAC3C,eAAe,EAAE,KAAK,CAAC,WAAW,QAAQ,CAAC,EAAE,SAAS;AAAA,IACtD,aAAa,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,SAAS;AAAA,IACxC,iBAAiB,EACd;AAAA,MACC,EAAE,KAAK;AAAA,QACL;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,MACF,CAAC;AAAA,IACH,EACC,SAAS;AAAA,IACZ,kBAAkB,EAAE,QAAQ,EAAE,SAAS;AAAA,IACvC,cAAc,EAAE,KAAK,CAAC,UAAU,QAAQ,OAAO,CAAC,EAAE,SAAS;AAAA,EAC7D,CAAC,EACA,OAAO;AAAA,EACV,WAAW,EACR,OAAO;AAAA,IACN,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS;AAAA,IACtC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS;AAAA,EACvC,CAAC,EACA,OAAO,EACP,SAAS;AAAA,EACZ,OAAO,EACJ;AAAA,IACC,EACG,OAAO;AAAA,MACN,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,MACtB,WAAW,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,MAC3B,WAAW,EAAE,OAAO,EAAE,SAAS;AAAA,MAC/B,YAAY,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,IAC9B,CAAC,EACA,OAAO;AAAA,EACZ,EACC,SAAS;AACd,CAAC,EACA,OAAO;","names":[]}

package/dist/index.js

@@ -106,6 +106,10 @@ function isConfigFile(filePath) {
 function isPackageJson(filePath) {
   return filePath === "package.json" || filePath.endsWith("/package.json");
 }
+function isGeneratedFile(filePath) {
+  const segments = filePath.split("/");
+  return segments.includes("gen") || (segments.at(-1) ?? "").includes(".gen.");
+}
 function isManagedFile(filePath) {
   return isPackageJson(filePath) || filePath === "pnpm-lock.yaml" || isConfigFile(filePath);
 }
@@ -216,7 +220,7 @@ import process4 from "process";
 // package.json
 var package_default = {
   name: "@cellajs/cli",
-  version: "0.2.2",
+  version: "0.2.3",
   private: false,
   license: "MIT",
   description: "CLI for managing your monorepo and syncing with upstream Cella.",
@@ -705,6 +709,55 @@ function printProtectedConflicts(result) {
   }
   console.info(colors_default.dim(`  ${PROTECTED_BEHIND_HINT}`));
 }
+function plural(count, singular, pluralForm = `${singular}s`) {
+  return `${count} ${count === 1 ? singular : pluralForm}`;
+}
+function shellPath(path4) {
+  return /^[\w./@+-]+$/.test(path4) ? path4 : `'${path4.replace(/'/g, `'\\''`)}'`;
+}
+function printIgnoredUpstreamChanges(result) {
+  const groups = result.ignoredUpstreamChanges ?? [];
+  if (groups.length === 0) return;
+  const total = groups.reduce((count, group) => count + group.paths.length, 0);
+  console.info();
+  console.info(
+    `${warningMark} ${colors_default.yellow(`ignored paths changed upstream \xB7 ${plural(total, "file")} under ${plural(groups.length, "entry", "entries")}`)}`
+  );
+  for (const group of groups) {
+    const counts = [plural(group.paths.length, "file")];
+    if (group.added > 0) counts.push(`${group.added} new`);
+    if (group.deleted > 0) counts.push(`${group.deleted} deleted`);
+    console.info(`  ${statusConfig.ignored.icon} ${group.entry} ${colors_default.dim(`\xB7 ${counts.join(", ")}`)}`);
+    if (result.upstreamDiffRange) {
+      console.info(colors_default.dim(`    git diff ${result.upstreamDiffRange} -- ${shellPath(group.entry)}`));
+    }
+  }
+  console.info(colors_default.dim("  the fork left these untouched and ignored paths never sync: diff and adopt what you need."));
+}
+function printUpstreamOverrideChanges(result) {
+  const report = result.upstreamOverrides;
+  if (!report) return;
+  console.info();
+  if (report.kind === "unreadable") {
+    const side = report.side === "base" ? "the last sync point" : "the incoming ref";
+    console.info(
+      colors_default.dim(`upstream overrides not compared: upstream ${CONFIG_FILE} is missing or unreadable at ${side}`)
+    );
+    return;
+  }
+  const lines = [];
+  for (const list of ["pinned", "ignored"]) {
+    for (const entry of report[list].added) lines.push(`  ${colors_default.green("+")} ${list}: ${entry}`);
+    for (const entry of report[list].removed) {
+      lines.push(`  ${colors_default.red("\u2212")} ${list}: ${entry}${colors_default.dim(" \xB7 dropped upstream, still in your config")}`);
+    }
+  }
+  console.info(
+    `${warningMark} ${colors_default.yellow(`upstream changed its sync overrides \xB7 ${plural(lines.length, "entry", "entries")} to review`)}`
+  );
+  for (const line of lines) console.info(line);
+  console.info(colors_default.dim(`  ${CONFIG_FILE} never syncs: add or drop these by hand where they fit your app.`));
+}
 function findMaskingPins(files) {
   return files.filter(
     (file) => file.isPinned && !isManagedFile(file.path) && file.status === "behind" && file.existsInFork && file.existsInUpstream
@@ -762,6 +815,23 @@ function isPinned(filePath, config) {
   if (isManagedFile(filePath)) return true;
   return isUnderAnyFolder(filePath, config.overrides?.pinned || []);
 }
+function groupIgnoredUpstreamChanges(files, ignored) {
+  const entries = [...new Set(ignored.map((entry) => entry.replace(/\/+$/, "")).filter(Boolean))];
+  const mostSpecificFirst = [...entries].sort((a, b) => b.length - a.length);
+  const groups = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    if (!file.upstreamOnly || isManagedFile(file.path) || isGeneratedFile(file.path)) continue;
+    const entry = mostSpecificFirst.find((candidate) => isUnderAnyFolder(file.path, [candidate]));
+    if (!entry) continue;
+    const group = groups.get(entry) ?? { entry, paths: [], added: 0, deleted: 0 };
+    group.paths.push(file.path);
+    if (!file.existsInFork) group.added++;
+    if (!file.existsInUpstream) group.deleted++;
+    groups.set(entry, group);
+  }
+  for (const group of groups.values()) group.paths.sort();
+  return entries.flatMap((entry) => groups.get(entry) ?? []);
+}
 function isPinnedForSync(filePath, config, unpinned) {
   if (isManagedFile(filePath)) return true;
   if (unpinned) return false;
@@ -1791,7 +1861,115 @@ function registerSignalHandlers() {
   cleanupRegistered = true;
 }
 
+// src/utils/upstream-overrides.ts
+import { Node, Project as Project2, SyntaxKind as SyntaxKind2 } from "ts-morph";
+var LIST_KEYS = ["pinned", "ignored"];
+function resolveExpression(node, sourceFile, depth = 0) {
+  if (!node || depth > 8) return node;
+  if (Node.isParenthesizedExpression(node) || Node.isAsExpression(node) || Node.isSatisfiesExpression(node)) {
+    return resolveExpression(node.getExpression(), sourceFile, depth + 1);
+  }
+  if (Node.isIdentifier(node)) {
+    return resolveExpression(
+      sourceFile.getVariableDeclaration(node.getText())?.getInitializer(),
+      sourceFile,
+      depth + 1
+    );
+  }
+  return node;
+}
+function findConfigObject(sourceFile) {
+  for (const call of sourceFile.getDescendantsOfKind(SyntaxKind2.CallExpression)) {
+    if (call.getExpression().getText() !== "defineConfig") continue;
+    const arg = resolveExpression(call.getArguments()[0], sourceFile);
+    if (Node.isObjectLiteralExpression(arg)) return arg;
+  }
+  const exported = sourceFile.getExportAssignment((assignment) => !assignment.isExportEquals());
+  const value = resolveExpression(exported?.getExpression(), sourceFile);
+  return Node.isObjectLiteralExpression(value) ? value : void 0;
+}
+function readProperty(object, name, sourceFile) {
+  for (const property of object.getProperties()) {
+    if (Node.isPropertyAssignment(property)) {
+      if (property.getName().replace(/^['"`]|['"`]$/g, "") !== name) continue;
+      return resolveExpression(property.getInitializer(), sourceFile) ?? null;
+    }
+    if (Node.isShorthandPropertyAssignment(property) && property.getName() === name) {
+      return resolveExpression(property.getNameNode(), sourceFile) ?? null;
+    }
+  }
+  return void 0;
+}
+function parseOverrideLists(source) {
+  try {
+    const project = new Project2({ useInMemoryFileSystem: true, skipLoadingLibFiles: true });
+    const sourceFile = project.createSourceFile("cella.config.ts", source);
+    const config = findConfigObject(sourceFile);
+    if (!config) return null;
+    const overrides = readProperty(config, "overrides", sourceFile);
+    if (overrides === void 0) return { pinned: [], ignored: [] };
+    if (!overrides || !Node.isObjectLiteralExpression(overrides)) return null;
+    const lists = { pinned: [], ignored: [] };
+    for (const key of LIST_KEYS) {
+      const list = readProperty(overrides, key, sourceFile);
+      if (list === void 0) continue;
+      if (!list || !Node.isArrayLiteralExpression(list)) return null;
+      for (const element of list.getElements()) {
+        if (Node.isStringLiteral(element) || Node.isNoSubstitutionTemplateLiteral(element)) {
+          lists[key].push(element.getLiteralValue());
+        }
+      }
+    }
+    return lists;
+  } catch {
+    return null;
+  }
+}
+function normalizeEntry(entry) {
+  return entry.trim().replace(/^\.\//, "").replace(/\/+$/, "");
+}
+function diffOverrideLists(base, incoming, fork) {
+  const diff = (key) => {
+    const baseSet = new Set(base[key].map(normalizeEntry).filter(Boolean));
+    const incomingSet = new Set(incoming[key].map(normalizeEntry).filter(Boolean));
+    const forkEntries = fork[key].map(normalizeEntry).filter(Boolean);
+    return {
+      added: [...incomingSet].filter((entry) => !baseSet.has(entry) && !isUnderAnyFolder(entry, forkEntries)),
+      removed: [...baseSet].filter((entry) => !incomingSet.has(entry) && forkEntries.includes(entry))
+    };
+  };
+  return { pinned: diff("pinned"), ignored: diff("ignored") };
+}
+async function readConfigSourceAtRef(repoPath, ref) {
+  for (const path4 of CONFIG_FILE_PATHS) {
+    const source = await git(["show", `${ref}:${path4}`], repoPath, { ignoreErrors: true });
+    if (source) return source;
+  }
+  return null;
+}
+async function compareUpstreamOverrides(repoPath, mergeBaseRef, incomingRef, forkConfig) {
+  const [baseSource, incomingSource] = await Promise.all([
+    readConfigSourceAtRef(repoPath, mergeBaseRef),
+    readConfigSourceAtRef(repoPath, incomingRef)
+  ]);
+  if (baseSource === incomingSource) return void 0;
+  const base = baseSource === null ? null : parseOverrideLists(baseSource);
+  if (!base) return { kind: "unreadable", side: "base" };
+  const incoming = incomingSource === null ? null : parseOverrideLists(incomingSource);
+  if (!incoming) return { kind: "unreadable", side: "incoming" };
+  const fork = {
+    pinned: forkConfig.overrides?.pinned ?? [],
+    ignored: forkConfig.overrides?.ignored ?? []
+  };
+  const changes = diffOverrideLists(base, incoming, fork);
+  const count = LIST_KEYS.reduce((n, key) => n + changes[key].added.length + changes[key].removed.length, 0);
+  return count > 0 ? { kind: "changes", ...changes } : void 0;
+}
+
 // src/services/analyze-core.ts
+function isReportableIgnored(filePath) {
+  return !isManagedFile(filePath) && !isGeneratedFile(filePath);
+}
 async function analyzeRefs(repoPath, localRef, incomingRef, mergeBaseRef, predicates, onProgress) {
   onProgress?.("collecting file hashes (batch)...");
   const [forkHashes, upstreamHashes, baseHashes] = await Promise.all([
@@ -1870,6 +2048,7 @@ async function analyzeRefs(repoPath, localRef, incomingRef, mergeBaseRef, predic
         status = "renamed";
         renamedFrom = oldPath;
       }
+      const upstreamOnly2 = fileIsIgnored && !forkModifiedOld && isReportableIgnored(filePath);
       analyzedFiles.push({
         path: filePath,
         status,
@@ -1878,7 +2057,8 @@ async function analyzeRefs(repoPath, localRef, incomingRef, mergeBaseRef, predic
         existsInFork: inFork,
         existsInUpstream: true,
         renamedFrom,
-        upstreamChanged: upstreamChanged2
+        upstreamChanged: upstreamChanged2,
+        upstreamOnly: upstreamOnly2 || void 0
       });
       continue;
     }
@@ -1913,6 +2093,7 @@ async function analyzeRefs(repoPath, localRef, incomingRef, mergeBaseRef, predic
       }
     }
     const upstreamChanged = (fileIsPinned || fileIsIgnored) && inUpstream && upstreamHash !== baseHash && forkHash !== baseHash;
+    const upstreamOnly = fileIsIgnored && isReportableIgnored(filePath) && upstreamHash !== baseHash && forkHash === baseHash;
     analyzedFiles.push({
       path: filePath,
       status,
@@ -1920,7 +2101,8 @@ async function analyzeRefs(repoPath, localRef, incomingRef, mergeBaseRef, predic
       isPinned: fileIsPinned,
       existsInFork: inFork,
       existsInUpstream: inUpstream,
-      upstreamChanged: upstreamChanged || void 0
+      upstreamChanged: upstreamChanged || void 0,
+      upstreamOnly: upstreamOnly || void 0
     });
   }
   const flagged = analyzedFiles.filter((file) => file.upstreamChanged && !renamedProtected.has(file.path));
@@ -2236,6 +2418,24 @@ function resultMeta(config, ctx) {
     upstreamCommits: ctx.upstreamCommits
   };
 }
+async function upstreamOnlyReports(config, ctx, files) {
+  const { forkPath } = config;
+  try {
+    const [baseSha, upstreamSha, upstreamOverrides] = await Promise.all([
+      getShortSha(forkPath, ctx.mergeBase),
+      // the commit, not an annotated release tag object
+      getShortSha(forkPath, ctx.upstreamCommit.hash),
+      compareUpstreamOverrides(forkPath, ctx.mergeBase, ctx.upstreamRef, config)
+    ]);
+    return {
+      upstreamDiffRange: `${baseSha}..${upstreamSha}`,
+      upstreamOverrides,
+      ignoredUpstreamChanges: groupIgnoredUpstreamChanges(files, config.overrides?.ignored ?? [])
+    };
+  } catch {
+    return {};
+  }
+}
 async function runSyncMerge(config, ctx, onProgress, onStep) {
   const { forkPath } = config;
   const { upstreamRef, releaseTag, mergeBase, upstreamGitHubUrl, upstreamCommit } = ctx;
@@ -2287,7 +2487,8 @@ async function runSyncMerge(config, ctx, onProgress, onStep) {
     conflicts: remainingConflicts,
     autoMergedFiles,
     protectedConflicts,
-    ...resultMeta(config, ctx)
+    ...resultMeta(config, ctx),
+    ...await upstreamOnlyReports(config, ctx, analyzedFiles)
   };
 }
 async function runAnalyzePreview(config, ctx, onProgress, onStep) {
@@ -2314,6 +2515,7 @@ async function runAnalyzePreview(config, ctx, onProgress, onStep) {
     onProgress
   );
   await enrichChangeInfo(forkPath, analyzedFiles, ctx.mergeBase, "HEAD", ctx.upstreamRef);
+  const reports = await upstreamOnlyReports(config, ctx, analyzedFiles);
   onStep?.("analysis complete", `${analyzedFiles.length} files analyzed, dry run \u2014 no changes applied`);
   onProgress?.("cleaning up worktree...");
   await cleanupWorktree(forkPath, worktreePath);
@@ -2324,7 +2526,8 @@ async function runAnalyzePreview(config, ctx, onProgress, onStep) {
     // For analyze mode, count diverged files as potential conflicts
     conflicts: analyzedFiles.filter((f) => f.status === "diverged").map((f) => f.path),
     protectedConflicts: analyzedFiles.filter((f) => f.upstreamChanged).map((f) => f.path),
-    ...resultMeta(config, ctx)
+    ...resultMeta(config, ctx),
+    ...reports
   };
 }
 async function runMergeEngine(config, options) {
@@ -2348,10 +2551,13 @@ var scopeStatuses = {
   risk: /* @__PURE__ */ new Set(["drifted", "diverged"]),
   protected: /* @__PURE__ */ new Set(["ahead"])
 };
-function filterByScope(files, scope) {
+function filterByScope(result, scope) {
   const statuses = scopeStatuses[scope];
-  const includeProtectedBehind = scope !== "risk";
-  return files.filter((f) => statuses.has(f.status) || includeProtectedBehind && f.upstreamChanged === true);
+  if (scope === "risk") return result.files.filter((f) => statuses.has(f.status));
+  const overridesChanged = result.upstreamOverrides?.kind === "changes";
+  return result.files.filter(
+    (f) => statuses.has(f.status) || f.upstreamChanged === true || f.upstreamOnly === true || overridesChanged && f.path === CONFIG_FILE
+  );
 }
 function findTargetFile(files, targetPath) {
   const exact = files.find((f) => f.path === targetPath);
@@ -2378,7 +2584,7 @@ async function runAnalyze(config) {
     }
   });
   spinnerSuccess();
-  const scopedFiles = filterByScope(result.files, config.scope ?? "all");
+  const scopedFiles = filterByScope(result, config.scope ?? "all");
   if (config.diff) {
     const file = findTargetFile(scopedFiles, config.diff) ?? findTargetFile(result.files, config.diff);
     if (!file) throw new Error(`file not found in analysis results: ${config.diff}`);
@@ -2386,6 +2592,7 @@ async function runAnalyze(config) {
     return result;
   }
   if (config.json) {
+    const overrides = result.upstreamOverrides?.kind === "changes" ? result.upstreamOverrides : void 0;
     const out = scopedFiles.map((f) => ({
       path: f.path,
       status: f.status,
@@ -2395,7 +2602,10 @@ async function runAnalyze(config) {
       upstreamCommit: f.upstreamCommit ?? null,
       upstreamChanged: f.upstreamChanged ?? false,
       upstreamChangedLines: f.upstreamChangedLines ?? null,
-      upstreamLinesAbsent: f.upstreamLinesAbsent ?? null
+      upstreamLinesAbsent: f.upstreamLinesAbsent ?? null,
+      upstreamOnly: f.upstreamOnly ?? false,
+      // Only on the sync config: upstream override entries the fork config does not follow
+      upstreamOverrides: overrides && f.path === CONFIG_FILE ? { pinned: overrides.pinned, ignored: overrides.ignored } : null
     }));
     writeStdout(JSON.stringify(out, null, 2));
     return result;
@@ -2436,6 +2646,8 @@ async function runAnalyze(config) {
   };
   printAnalysisFileGroups(result.files, linkOptions);
   printSummary(result.summary, "analysis summary");
+  printIgnoredUpstreamChanges(result);
+  printUpstreamOverrideChanges(result);
   printMaskingPinWarning(result.files);
   if (config.logFile) {
     const logPath = writeLogFile(config.forkPath, result.files);
@@ -4204,6 +4416,8 @@ async function runSync(config, options) {
     spinnerFail("sync completed with conflicts");
   }
   printSummary(result.summary, "merge summary");
+  printIgnoredUpstreamChanges(result);
+  printUpstreamOverrideChanges(result);
   printMaskingPinWarning(result.files);
   if (config.logFile) {
     const logPath = writeLogFile(config.forkPath, result.files);
@@ -4820,9 +5034,9 @@ function fmtPct(value, total) {
 function printStats(stats, verbose) {
   console.info();
   console.info(
-    `  ${colors_default.bold("source files")}  ${String(stats.total)}  ${colors_default.dim(`(${stats.skipped} non-source skipped)`)}`
+    `  ${colors_default.bold("code files".padEnd(13))}  ${String(stats.total)}  ${colors_default.dim(`(${[...sourceExtensions].join(" ")})`)}`
   );
-  console.info(`  ${colors_default.bold("lines of code")} ${colors_default.cyan(formatLoc(stats.totalLoc))}`);
+  console.info(`  ${colors_default.bold("lines of code")}  ${colors_default.cyan(formatLoc(stats.totalLoc))}`);
   console.info();
   const catEntries = [
     ["source & config", stats.categories.other],
@@ -4852,6 +5066,7 @@ function printStats(stats, verbose) {
       );
     }
   } else {
+    console.info(colors_default.dim("  source & config by package"));
     for (const [name, data] of Object.entries(stats.packages)) {
       const srcFiles = data.categories.other.files;
       const srcLoc = data.categories.other.loc;