Skip to content

Commit 15a7d69

Browse files
committed
docs(plugin-email): re-anchor the dead tracker citations to the commits that decided them
Sixteen comment and docblock sites under packages/plugins/plugin-email/src cited tracker numbers that no longer resolve. Each now cites the commit in this repository's history that decided what the line describes: - #8675 -> c9f5950 (sys_account OAuth tokens internal; the key-absence trap on optional columns and the absenceProvesStrip discriminator) - #11741 -> b706af9 (SendEmailInput.organizationId, stamped pass-through onto sys_email by its producers) - #13189 -> 33fbd35 (the SMTP port guard tests integrality, and the generated refusal sentence says so) - #13190 -> 56c5b1d (a present-but-unreadable smtp_port reaches the guard instead of silently falling back to 587) Comments only: 16 lines out, 16 in, every file keeps its line count, and no code token moves. Test titles carrying these numbers are string tokens and are left. Claude-Session: https://claude.ai/code/session_01XY5uCwTjZj7884yYtyur4H Co-authored-by: Claude <noreply@anthropic.com>
1 parent 97005ae commit 15a7d69

8 files changed

Lines changed: 16 additions & 16 deletions

File tree

‎packages/plugins/plugin-email/src/email-headers-internal.integration.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -248,7 +248,7 @@ describe('sys_email.headers_json — authored headers vs the data API (#8149)',
248248
});
249249

250250
it('a message authored WITHOUT headers still delivers — the optional-column trap', async () => {
251-
// The regression PR #8675 measured on a sibling card: `headers_json` is
251+
// The regression commit c9f595083 records from a sibling card: `headers_json` is
252252
// `required: false`, and the overwhelming majority of real rows have no
253253
// custom headers at all. A seam that inferred "key missing ⇒ the strip
254254
// ran" would treat every ordinary email as a redacted row. This pins that

‎packages/plugins/plugin-email/src/email-service.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -339,7 +339,7 @@ describe('rowToNormalized', () => {
339339
});
340340
});
341341

342-
// ── #11741 — sys_email organization stamping ────────────────────────────────
342+
// ── Commit b706af987 — sys_email organization stamping ──────────────────────
343343
// The writer runs under a constant SYSTEM context, so the ONLY organization a
344344
// row can carry is the one the input carries: `SendEmailInput.organizationId`
345345
// is stamped onto `sys_email.organization_id` verbatim (pass-through), and its

‎packages/plugins/plugin-email/src/email-service.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -739,7 +739,7 @@ export class EmailService implements IEmailService {
739739
...(input.relatedObject ? { related_object: input.relatedObject } : {}),
740740
...(input.relatedId ? { related_id: input.relatedId } : {}),
741741
...(input.sentBy ? { sent_by: input.sentBy } : {}),
742-
// #11741 — pass-through ONLY. This writer runs under a constant system
742+
// Commit b706af987 — pass-through ONLY. This writer runs under a constant system
743743
// context, so the input's organization is the one fact it may stamp:
744744
// no resolution, no default, no fabrication (a wrong organization_id is
745745
// worse than a null). Absent ⇒ the column stays unwritten.
@@ -1436,7 +1436,7 @@ export class EmailService implements IEmailService {
14361436
...(input.relatedObject ? { relatedObject: input.relatedObject } : {}),
14371437
...(input.relatedId ? { relatedId: input.relatedId } : {}),
14381438
...(input.sentBy ? { sentBy: input.sentBy } : {}),
1439-
// #11741 — sendTemplate is itself a producer of send(): forward the
1439+
// Commit b706af987 — sendTemplate is itself a producer of send(): forward the
14401440
// caller's organization so the sys_email row it persists is stamped.
14411441
...(input.organizationId ? { organizationId: input.organizationId } : {}),
14421442
};

‎packages/plugins/plugin-email/src/internal-header-readback.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@
3434
* majority of real rows have no custom headers at all. Under a key-absence
3535
* inference every ordinary header-less email would look like a redacted row
3636
* and force a privileged read, and an engine without the accessor would fail
37-
* every ordinary send. (PR #8675 hit exactly this on `sys_account`'s optional
37+
* every ordinary send. (Commit c9f595083 records exactly this on `sys_account`'s optional
3838
* token columns: inheriting "key missing ⇒ the strip ran" from a
3939
* `required: true` column broke ordinary sign-in, 16 red tests.) The schema
4040
* flag is cardinality-independent: it is true when the engine redacts and

‎packages/plugins/plugin-email/src/transports/smtp-port-contract.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@
3131
* mechanism `mail-manifest-providers.contract.test.ts` already uses for the
3232
* provider dropdown over that same devDependency.
3333
*
34-
* ## #13189 — the accept set narrowed, and this file is where that is visible
34+
* ## Commit 33fbd3566 — the accept set narrowed, and this file is where that is visible
3535
*
3636
* `isValidSmtpPort` now tests INTEGRALITY. That is a deliberate narrowing of
3737
* the set #12993 pinned, and the pin below was written to make exactly this
@@ -225,7 +225,7 @@ describe('#12993 — one SMTP port range, every door states it from there', () =
225225
it('narrows the accept set in exactly ONE dimension — integrality — and nowhere else (#13189)', () => {
226226
// ⚠️ This case was `refactors the enforcement without narrowing what it
227227
// accepts` when #12993 moved the predicate here, and `587.5` sat in its
228-
// table as MEASURED, not endorsed. #13189 is the card that SPENDS that
228+
// table as MEASURED, not endorsed. Commit 33fbd3566 is the change that SPENDS that
229229
// pin: the accept set really does narrow now, and the pin's job was always
230230
// to make such a change visible rather than to prevent one. So the oracle
231231
// and the values stay exactly where they were; what changed is that the

‎packages/plugins/plugin-email/src/transports/smtp-port-contract.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,7 @@ export const SMTP_PORT_RANGE_TEXT = `${SMTP_PORT_MIN}-${SMTP_PORT_MAX}`;
8484
* Three conditions, and `Number.isInteger` carries the first two of them:
8585
* finite (it refuses `NaN` and both infinities), whole, and inside the range.
8686
*
87-
* ## ⭐ Why integrality is part of the contract (#13189)
87+
* ## ⭐ Why integrality is part of the contract (commit 33fbd3566)
8888
*
8989
* This predicate arrived from `smtp.ts` as `Number.isFinite` and no more, and
9090
* #12993 kept it that way on purpose — narrowing an accept set inside a
@@ -131,7 +131,7 @@ export function isValidSmtpPort(port: number): boolean {
131131
* `raw` is the caller's ORIGINAL value, not the coerced number: an operator
132132
* who configured `"abc"` needs to see `abc`, not `NaN`.
133133
*
134-
* ⭐ **"an integer" is load-bearing, not decoration (#13189).** This sentence
134+
* ⭐ **"an integer" is load-bearing, not decoration (commit 33fbd3566).** This sentence
135135
* used to read `(expected 1-65535)` while the guard admitted `587.5` — which
136136
* IS in 1-65535 — so the door stated a rule it did not enforce. Now that the
137137
* guard tests integrality, the sentence has to say so or the lie has merely

‎packages/plugins/plugin-email/src/transports/smtp.test.ts‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -218,7 +218,7 @@ describe('smtpOptionsFromMailSettings', () => {
218218
expect(smtpOptionsFromMailSettings({ smtp_host: 'smtp.x' })).toEqual({ host: 'smtp.x' });
219219
});
220220

221-
// #13190 — `absent` vs `present but unreadable`, which this function used to
221+
// Commit 56c5b1dbe — `absent` vs `present but unreadable`, which this function used to
222222
// collapse into one bucket. A port that could not be read was DELETED here,
223223
// and `SmtpTransport` then applied its built-in 587: a configured `abc`
224224
// became a working-looking connection nobody chose, and `describe()`
@@ -269,18 +269,18 @@ describe('smtpOptionsFromMailSettings', () => {
269269
});
270270

271271
it('refuses a READABLE but FRACTIONAL port by name, without a second door (#13189)', () => {
272-
// The bucket #13190 never had to name, because the guard below it
272+
// The bucket commit 56c5b1dbe never had to name, because the guard below it
273273
// admitted the value: `'587.5'` is present, readable, finite and inside
274274
// `1-65535`, so it mapped straight through and died at SEND time under
275275
// `RangeError: Port should be >= 0 and < 65536` — a TCP rule, naming no
276-
// part of Settings → Mail → Port. #13189 made the guard test
276+
// part of Settings → Mail → Port. Commit 33fbd3566 made the guard test
277277
// integrality, so it is refused at construction now, in this
278278
// transport's own sentence, carrying what the operator actually typed.
279279
const opts = smtpOptionsFromMailSettings({ smtp_host: 'smtp.x', smtp_port: '587.5' });
280280

281-
// ⛔ The mapping still PASSES IT THROUGH. #13190's rule is that this
281+
// ⛔ The mapping still PASSES IT THROUGH. Commit 56c5b1dbe's rule is that this
282282
// function hides nothing from the guard and adds no parallel refusal of
283-
// its own; #13189 changed which numbers the guard refuses, not where
283+
// its own; commit 33fbd3566 changed which numbers the guard refuses, not where
284284
// the refusal lives. A repair that started rejecting here instead would
285285
// pass the next line and quietly rebuild the second door.
286286
expect(opts, 'the mapping dropped the key instead of passing it down')

‎packages/plugins/plugin-email/src/transports/smtp.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ export interface SmtpTransportOptions {
6565
*
6666
* ⚠️ An **integer** in `1-65535`, refused at construction otherwise —
6767
* `number` cannot say that in the type, and a fractional port is not a
68-
* near miss but an address `net.connect` will never accept (#13189).
68+
* near miss but an address `net.connect` will never accept (commit 33fbd3566).
6969
*/
7070
port?: number;
7171
/**
@@ -124,7 +124,7 @@ export class SmtpTransport implements IEmailTransport {
124124
// below is GENERATED from it. A hand-written `(expected 1-65535)` on this
125125
// line is exactly the drift #12993 removed: it sat next to the check it
126126
// described, so the two could disagree and nothing would fail — which is
127-
// not hypothetical. They DID disagree until #13189: the check admitted
127+
// not hypothetical. They DID disagree until commit 33fbd3566: the check admitted
128128
// `587.5` and the sentence said `1-65535`, a range `587.5` satisfies. The
129129
// guard tests integrality now and the generated sentence says so, so the
130130
// two still cannot drift apart without one of them being rewritten.

0 commit comments

Comments
 (0)