@futurelastic/colab-handbook 1.12.0-rc.48 → 1.12.0-rc.49

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -27,5 +27,5 @@
27
27
  "engines": {
28
28
  "node": ">=18"
29
29
  },
30
- "version": "1.12.0-rc.48"
30
+ "version": "1.12.0-rc.49"
31
31
  }
package/tools/colab CHANGED
@@ -7678,7 +7678,10 @@ function adoptGitExtras(repoAbs, opts = {}) {
7678
7678
  // #449: `git ls-files` for the migrations candidate scan (adopt never asks `migrations:`).
7679
7679
  const ls = git.git(['ls-files'], repoAbs);
7680
7680
  const trackedFiles = ls.ok ? ls.stdout.split('\n').filter(Boolean) : undefined;
7681
- return { trunk, trunkSource, hooksPath, hooksDirFiles, trackedFiles, fork: adoptDetectFork(repoAbs, opts) };
7681
+ // #483: the fork's own owner, from origin's URL — what an inherited CODEOWNERS team is compared to.
7682
+ const originUrl = git.git(['remote', 'get-url', 'origin'], repoAbs);
7683
+ const ownOrg = originUrl.ok ? codeowners.remoteOwner(originUrl.stdout) : null;
7684
+ return { trunk, trunkSource, hooksPath, hooksDirFiles, trackedFiles, fork: adoptDetectFork(repoAbs, opts), ownOrg };
7682
7685
  }
7683
7686
 
7684
7687
  /**
@@ -7932,6 +7935,12 @@ function printAdoptReport(report, repoAbs, verify, localFinish) {
7932
7935
  print(`stack candidates: ${report.detected.stackCandidates.length ? report.detected.stackCandidates.join(', ') : '(none found)'}`);
7933
7936
  print(`declared ports: ${fmtVal(report.detected.ports)}`);
7934
7937
  if (report.fork) print(`fork of an upstream: yes — ${report.fork.source === 'flag' ? '--fork' : `remote "${report.fork.remote}" ${report.fork.url}`} (step 5 is the append-only block, §9 "A fork of an upstream")`);
7938
+ if (report.inheritedCodeowners) {
7939
+ const ic = report.inheritedCodeowners;
7940
+ print(`⚠ inherited CODEOWNERS: ${ic.path} names ${ic.teams.join(', ')} — team(s) of an org other than ${ic.ownOrg}. ` +
7941
+ 'colab ship ignores them on this fork, so they gate no landing here; write the fork\'s own owners into that file ' +
7942
+ '(a fork patch) if some paths here should need a review (§2 "Core paths", #483)');
7943
+ }
7935
7944
  print(`legacy tier letter, derived from (production, deploy): ${report.legacyTierLetter ?? '(undetermined — production is set but deploy matches none of push-main/tag/manual)'}`);
7936
7945
  print('');
7937
7946
  print('Derived consequences:');
@@ -9924,7 +9933,8 @@ Options:
9924
9933
  instead — an unattended caller must NOT read it as a no-op. "pr-pending"
9925
9934
  (#350) means a real run would open/reuse a PR and PAUSE (exit 3) — additive
9926
9935
  keys \`coreReview\` ({ active, verdict, inertReason, codeownersPath, corePaths,
9927
- headSha, pr, approval }) and \`machineTrailer\` ("Machine: <label>") say why.
9936
+ ignoredOwners (#483: a fork's inherited foreign-org teams), headSha, pr,
9937
+ approval }) and \`machineTrailer\` ("Machine: <label>") say why.
9928
9938
  \`machineTrailer\` is null whenever the trailer is omitted (#367), and
9929
9939
  \`machineTrailerDecision\` ({ include, reason, visibility, room, failClosed },
9930
9940
  null on evidence-close) says which way the squash will go and why.
@@ -11763,6 +11773,19 @@ function readTargetCodeowners(repoAbs, target) {
11763
11773
  return null;
11764
11774
  }
11765
11775
 
11776
+ /**
11777
+ * #483: is this repo a fork, and which org owns it? The fork test is adopt's own (#449: a remote named
11778
+ * `upstream` whose URL differs from origin's), so adopt and ship never disagree about the shape; the
11779
+ * owner is read from this repo's remote URL. Either unknown → `{ fork: false }`, nothing is dropped.
11780
+ */
11781
+ function codeownersForkContext(repoAbs) {
11782
+ if (!adoptDetectFork(repoAbs)) return { fork: false, ownOrg: null };
11783
+ const name = git.remoteInfo(repoAbs).name || 'origin';
11784
+ const u = git.git(['remote', 'get-url', name], repoAbs);
11785
+ const ownOrg = u.ok ? codeowners.remoteOwner(u.stdout) : null;
11786
+ return { fork: !!ownOrg, ownOrg };
11787
+ }
11788
+
11766
11789
  function branchChangedPathsNoRenames(repoAbs, base, ref) {
11767
11790
  const r = git.git(['diff', '--name-only', '--no-renames', `${base}...${ref}`], repoAbs);
11768
11791
  return r.ok ? r.stdout.split('\n').map((s) => s.trim()).filter(Boolean) : null;
@@ -11806,21 +11829,30 @@ function shipDirectCoreReview(repoAbs, gh, trunk, since) {
11806
11829
  }
11807
11830
  }
11808
11831
  }
11809
- return codeowners.directVerdict({ files: [before, readTargetCodeowners(repoAbs, trunk)], authors, changed });
11832
+ return codeowners.directVerdict({ files: [before, readTargetCodeowners(repoAbs, trunk)], authors, changed, fork: codeownersForkContext(repoAbs) });
11810
11833
  }
11811
11834
 
11812
11835
  function shipCoreReview(repoAbs, gh, target, branch) {
11813
- const out = { active: false, inertReason: null, codeownersPath: null, warnings: [], corePaths: [],
11836
+ const out = { active: false, inertReason: null, codeownersPath: null, warnings: [], corePaths: [], ignoredOwners: [],
11814
11837
  pr: null, approval: null, headSha: null, authors: [], verdict: 'inert', detail: '' };
11815
11838
  const file = readTargetCodeowners(repoAbs, target);
11816
11839
  if (!file) { out.inertReason = `no CODEOWNERS on ${target}`; out.detail = `inert: ${out.inertReason}`; return out; }
11817
11840
  out.codeownersPath = file.path;
11818
- const { rules, warnings } = codeowners.parse(file.text);
11819
- out.warnings = warnings;
11841
+ const parsedFile = codeowners.parse(file.text);
11842
+ out.warnings = parsedFile.warnings;
11843
+ // #483: on a fork, teams of another org (inherited from the upstream) bind nothing here.
11844
+ const forkCtx = codeownersForkContext(repoAbs);
11845
+ const { rules, dropped } = codeowners.dropForeignTeams(parsedFile.rules, forkCtx);
11846
+ out.ignoredOwners = dropped;
11847
+ if (dropped.length) out.warnings = [...out.warnings, codeowners.foreignNote(dropped, forkCtx)];
11820
11848
  const parsed = branchName.parse(branch);
11821
11849
  out.authors = [...new Set([gh ? git.ghCurrentLogin() : null, parsed && parsed.login].filter(Boolean))];
11822
11850
  const inert = codeowners.inert(rules, out.authors);
11823
- if (inert.inert) { out.inertReason = inert.reason; out.detail = `inert: ${inert.reason}`; return out; }
11851
+ if (inert.inert) {
11852
+ out.inertReason = dropped.length ? `${inert.reason} once the fork's inherited foreign-org teams are ignored (#483)` : inert.reason;
11853
+ out.detail = `inert: ${out.inertReason}`;
11854
+ return out;
11855
+ }
11824
11856
  out.active = true;
11825
11857
  const ref = shipRefFor(repoAbs, branch);
11826
11858
  out.headSha = git.git(['rev-parse', ref], repoAbs).stdout || null;
@@ -11881,7 +11913,7 @@ function coreReviewPayload(cr) {
11881
11913
  if (!cr) return null;
11882
11914
  return {
11883
11915
  active: cr.active, verdict: cr.verdict, inertReason: cr.inertReason, codeownersPath: cr.codeownersPath,
11884
- corePaths: cr.corePaths.map((c) => c.path), headSha: cr.headSha,
11916
+ ignoredOwners: cr.ignoredOwners || [], corePaths: cr.corePaths.map((c) => c.path), headSha: cr.headSha,
11885
11917
  pr: cr.pr ? { number: cr.pr.number, url: cr.pr.url, state: cr.pr.state } : null,
11886
11918
  approval: cr.approval,
11887
11919
  };
@@ -12522,7 +12554,8 @@ function cmdShip(argv) {
12522
12554
  if (coreReview.verdict === 'approved') {
12523
12555
  const reviewed = new Set(coreReview.corePaths.map((c) => c.path));
12524
12556
  const nowChanged = branchChangedPathsNoRenames(repoAbs, mergeRef, sess.branch) || [];
12525
- const { rules } = codeowners.parse((readTargetCodeowners(repoAbs, target) || {}).text || '');
12557
+ const { rules } = codeowners.dropForeignTeams(
12558
+ codeowners.parse((readTargetCodeowners(repoAbs, target) || {}).text || '').rules, codeownersForkContext(repoAbs));
12526
12559
  const unreviewed = codeowners.corePaths(rules, nowChanged).filter((c) => !reviewed.has(c.path));
12527
12560
  if (unreviewed.length) {
12528
12561
  cleanupEphemeral();
@@ -212,6 +212,25 @@ function deriveConsequences({ exposure, writes, room }) {
212
212
  // ---------------------------------------------------------------------- §9 remainder checklist
213
213
 
214
214
  const migrationPaths = require('./migration-paths.js');
215
+ const codeowners = require('./codeowners.js');
216
+
217
+ /**
218
+ * #483 — on a fork, the CODEOWNERS teams that belong to another org: inherited from the upstream,
219
+ * unable to review here, and therefore ignored by `colab ship`'s core-path reader (CONVENTIONS.md
220
+ * §2, *Core paths*). Adopt names them so the fork owner learns at adoption time, not at the first
221
+ * ship, that the inherited file is inert until the fork writes its own. Null when there is nothing
222
+ * to say: not a fork, the fork's owner unknown, no CODEOWNERS, or no foreign team in it.
223
+ */
224
+ function detectInheritedCodeowners(io, fork, ownOrg) {
225
+ if (!fork || !ownOrg) return null;
226
+ for (const p of codeowners.CODEOWNERS_PATHS) {
227
+ const text = io.readFile(p);
228
+ if (text === null || text === undefined) continue;
229
+ const teams = codeowners.foreignTeams(codeowners.parse(text).rules, { fork: true, ownOrg });
230
+ return teams.length ? { path: p, ownOrg, teams } : null;
231
+ }
232
+ return null;
233
+ }
215
234
 
216
235
  /**
217
236
  * #449 — the agent workflow an upstream ships inside the fork: entries under `.claude/skills/`
@@ -412,6 +431,7 @@ function detect(io, extra = {}) {
412
431
  // `upstream` whose URL differs from origin's) or takes `--fork`/`--no-fork`; null = not a fork.
413
432
  const fork = (extra && extra.fork) || null;
414
433
  const upstreamAgentFiles = fork ? detectUpstreamAgentFiles(io) : [];
434
+ const inheritedCodeowners = detectInheritedCodeowners(io, fork, (extra && extra.ownOrg) || null);
415
435
  // Only when the CLI handed over `git ls-files` — a pure-io caller without it gets no step-2 line
416
436
  // rather than a false "none detected".
417
437
  const migrations = extra && Array.isArray(extra.trackedFiles)
@@ -434,6 +454,7 @@ function detect(io, extra = {}) {
434
454
  consequences,
435
455
  fork,
436
456
  upstreamAgentFiles,
457
+ inheritedCodeowners,
437
458
  migrations,
438
459
  remaining: remainingSteps({ migrations, fork, upstreamAgentFiles }),
439
460
  };
@@ -1039,6 +1060,7 @@ function renderAgentsStub() {
1039
1060
  }
1040
1061
 
1041
1062
  module.exports = {
1063
+ detectInheritedCodeowners,
1042
1064
  renderClaudeShell,
1043
1065
  renderAgentsStub,
1044
1066
  ROW_NAMES,
@@ -121,6 +121,62 @@ function inert(rules, authors) {
121
121
  return { inert: false, reason: `CODEOWNERS names ${others.join(', ')}` };
122
122
  }
123
123
 
124
+ /**
125
+ * #483 — the owner (user or org) of a forge remote URL, lowercased, or null when the URL has no
126
+ * `<owner>/<repo>` shape this can read. Handles `https://host/owner/repo(.git)`,
127
+ * `ssh://git@host[:port]/owner/repo` and the scp form `git@host:owner/repo`.
128
+ */
129
+ function remoteOwner(url) {
130
+ const s = String(url || '').trim().replace(/\/+$/, '').replace(/\.git$/, '');
131
+ let m = /^[a-z][a-z0-9+.-]*:\/\/[^/]+\/([^/]+)\/[^/]+$/i.exec(s);
132
+ if (!m) m = /^[^@/\s]+@[^:/\s]+:([^/]+)\/[^/]+$/.exec(s);
133
+ return m ? m[1].toLowerCase() : null;
134
+ }
135
+
136
+ const TEAM_RE = /^@([^/\s@]+)\/[^/\s]+$/;
137
+
138
+ /**
139
+ * #483 — the owner tokens a FORK must not be bound by: teams (`@org/team`) of an org other than
140
+ * the fork's own owner (`ownOrg`). A fork inherits the upstream's CODEOWNERS unchanged, and a team
141
+ * of another org cannot review in the fork at all, so honouring it would turn every landing into a
142
+ * human gate nobody here decided on (CONVENTIONS.md §2, *Core paths*, "A fork's inherited
143
+ * CODEOWNERS").
144
+ *
145
+ * Narrow on purpose — every doubt still resolves toward review: not a fork, or the fork's owner
146
+ * unknown, drops nothing; a login or an email is never dropped (a person can be a collaborator
147
+ * anywhere); a team of the fork's own org is kept.
148
+ */
149
+ function foreignTeams(rules, { fork, ownOrg } = {}) {
150
+ if (!fork || !ownOrg) return [];
151
+ const own = String(ownOrg).toLowerCase();
152
+ const out = new Set();
153
+ for (const r of rules || []) {
154
+ for (const o of r.owners) {
155
+ const m = TEAM_RE.exec(o);
156
+ if (m && m[1].toLowerCase() !== own) out.add(o);
157
+ }
158
+ }
159
+ return [...out];
160
+ }
161
+
162
+ /**
163
+ * #483 — `rules` with `foreignTeams` removed from every rule's owners. A rule left with no owner
164
+ * stays in place and, like an ownerless line, carves its paths out (the last match still wins), so
165
+ * an inherited `* @upstream/team` leaves the fork's own later lines exactly as they were.
166
+ * Returns `{ rules, dropped }`; `dropped` is `[]` (and `rules` the input) when nothing applies.
167
+ */
168
+ function dropForeignTeams(rules, ctx) {
169
+ const dropped = foreignTeams(rules, ctx);
170
+ if (!dropped.length) return { rules, dropped };
171
+ const gone = new Set(dropped);
172
+ return { rules: (rules || []).map((r) => ({ ...r, owners: r.owners.filter((o) => !gone.has(o)) })), dropped };
173
+ }
174
+
175
+ /** #483: the one-line reason a fork's foreign teams were ignored — shared by every reader. */
176
+ function foreignNote(dropped, ctx) {
177
+ return `fork of an upstream: ignored ${dropped.join(', ')} — team(s) of an org other than ${ctx.ownOrg}, inherited and unable to review here (#483)`;
178
+ }
179
+
124
180
  /**
125
181
  * Has a PR been approved by someone other than its author, AT `headSha`?
126
182
  *
@@ -168,8 +224,10 @@ function approvalVerdict(reviews, { prAuthor, authors = [], headSha }) {
168
224
  * rule is inert only when every file present is inert. Identical texts count once.
169
225
  * `changed`: every path the unit's commits touched, or null when they could not be listed. Null
170
226
  * refuses while the rule is active: an unbounded unit cannot be shown to avoid core paths.
227
+ * `fork`: `{ fork, ownOrg }` (#483) — on a fork, teams of another org are dropped from both files
228
+ * before anything else is read (`dropForeignTeams`). Absent = nothing dropped.
171
229
  */
172
- function directVerdict({ files, authors, changed }) {
230
+ function directVerdict({ files, authors, changed, fork = null }) {
173
231
  const out = { active: false, inertReason: null, codeownersPath: null, warnings: [], corePaths: [], verdict: 'inert', detail: '' };
174
232
  const seen = new Set();
175
233
  const present = (files || []).filter((f) => f && !seen.has(f.text) && seen.add(f.text));
@@ -178,8 +236,11 @@ function directVerdict({ files, authors, changed }) {
178
236
  const inertReasons = [];
179
237
  const activeReasons = [];
180
238
  for (const f of present) {
181
- const { rules, warnings } = parse(f.text);
182
- for (const w of warnings) out.warnings.push(`${f.path}@${f.ref}: ${w}`);
239
+ const parsed = parse(f.text);
240
+ for (const w of parsed.warnings) out.warnings.push(`${f.path}@${f.ref}: ${w}`);
241
+ // #483: a fork's inherited foreign-org teams bind neither file.
242
+ const { rules, dropped } = dropForeignTeams(parsed.rules, fork || {});
243
+ if (dropped.length) out.warnings.push(`${f.path}@${f.ref}: ${foreignNote(dropped, fork)}`);
183
244
  const iv = inert(rules, authors);
184
245
  if (iv.inert) { inertReasons.push(`${f.path}@${f.ref}: ${iv.reason}`); continue; }
185
246
  out.active = true;
@@ -205,4 +266,7 @@ function directVerdict({ files, authors, changed }) {
205
266
  return out;
206
267
  }
207
268
 
208
- module.exports = { CODEOWNERS_PATHS, parse, compile, ownerOf, corePaths, inert, approvalVerdict, directVerdict };
269
+ module.exports = {
270
+ CODEOWNERS_PATHS, parse, compile, ownerOf, corePaths, inert, approvalVerdict, directVerdict,
271
+ remoteOwner, foreignTeams, dropForeignTeams, foreignNote,
272
+ };