no-code-change-comment.json marker artifact module #304

New issue

david · 2026-09-05T18:35:02Z

david commented

2026-09-05 18:35:02 +00:00

Summary

Add the schema-validated no-code-change-comment.json marker artifact recording that the explanatory comment was successfully posted on the issue — written only after a successful post, checked before every post attempt (at-most-once, ADR-021 §6).

Background

The no-code-change comment path needs a durable, crash-safe record that the comment was posted. This mirrors the existing idempotency pattern from ADR-018 (mr-result.json) and the existing no-code-change artifact module (src/artifacts/services/noCodeChangeArtifact.ts + src/artifacts/helpers/validateNoCodeChange.ts): the marker is the single source of truth for "already commented" — absent → post, present → skip.

Absence of the file is the normal pre-post state and must read as undefined, not an error. A malformed file (e.g. a truncated write) is a real defect and must throw (ArtifactValidationError, same contract as readNoCodeChangeSignal). This module is standalone — no pipeline wiring in this step.

Implementation Details

Create src/artifacts/helpers/validateNoCodeChangeComment.ts, mirroring validateNoCodeChange.ts:

export interface NoCodeChangeCommentArtifact {
  /** Issue key the comment was posted on (e.g. `ABC-123`). */
  issueKey: string;
  /** ISO-8601 timestamp of the successful post. */
  postedAt: string;
}
export function validateNoCodeChangeCommentArtifact(
  value: unknown,
): NoCodeChangeCommentValidation;

Same validation-result shape as the existing validator: rejects missing/empty/whitespace issueKey, missing/empty/non-string postedAt, and non-object input.

Create src/artifacts/services/noCodeChangeCommentArtifact.ts, mirroring noCodeChangeArtifact.ts:
- NO_CODE_CHANGE_COMMENT_FILENAME = 'no-code-change-comment.json'
- noCodeChangeCommentPath(runDir): string
- writeNoCodeChangeCommentSignal(runDir, artifact) — validate first, then write.
- readNoCodeChangeCommentSignal(runDir) — returns undefined when the file is absent; throws ArtifactValidationError when content is malformed.
Export the filename constant, service functions, validator, and types from src/artifacts/index.ts.

Acceptance Criteria

validateNoCodeChangeCommentArtifact accepts { issueKey: 'ABC-123', postedAt: '<ISO-8601>' } and rejects missing/empty issueKey, missing/empty postedAt, and non-object input.
Write/read round-trip in a temp run dir returns the identical artifact.
Reading from a run dir without the file returns undefined.
Reading a malformed file throws ArtifactValidationError.
NO_CODE_CHANGE_COMMENT_FILENAME === 'no-code-change-comment.json' and noCodeChangeCommentPath places the file under the run dir.
All new symbols exported from src/artifacts/index.ts; unit tests in src/artifacts/helpers/validateNoCodeChangeComment.test.ts and src/artifacts/services/noCodeChangeCommentArtifact.test.ts pass.

Test Plan

Targeted unit tests per above (temp run-dir fixtures): npx vitest run src/artifacts/helpers/validateNoCodeChangeComment.test.ts src/artifacts/services/noCodeChangeCommentArtifact.test.ts
npm run lint clean.

## Summary Add the schema-validated `no-code-change-comment.json` marker artifact recording that the explanatory comment was successfully posted on the issue — written only after a successful post, checked before every post attempt (at-most-once, ADR-021 §6). ## Background The no-code-change comment path needs a durable, crash-safe record that the comment was posted. This mirrors the existing idempotency pattern from ADR-018 (`mr-result.json`) and the existing no-code-change artifact module (`src/artifacts/services/noCodeChangeArtifact.ts` + `src/artifacts/helpers/validateNoCodeChange.ts`): the marker is the **single source of truth** for "already commented" — absent → post, present → skip. Absence of the file is the normal pre-post state and must read as `undefined`, not an error. A malformed file (e.g. a truncated write) is a real defect and must throw (`ArtifactValidationError`, same contract as `readNoCodeChangeSignal`). This module is standalone — no pipeline wiring in this step. ## Implementation Details - Create `src/artifacts/helpers/validateNoCodeChangeComment.ts`, mirroring `validateNoCodeChange.ts`: ```typescript export interface NoCodeChangeCommentArtifact { /** Issue key the comment was posted on (e.g. `ABC-123`). */ issueKey: string; /** ISO-8601 timestamp of the successful post. */ postedAt: string; } export function validateNoCodeChangeCommentArtifact( value: unknown, ): NoCodeChangeCommentValidation; ``` Same validation-result shape as the existing validator: rejects missing/empty/whitespace `issueKey`, missing/empty/non-string `postedAt`, and non-object input. - Create `src/artifacts/services/noCodeChangeCommentArtifact.ts`, mirroring `noCodeChangeArtifact.ts`: - `NO_CODE_CHANGE_COMMENT_FILENAME = 'no-code-change-comment.json'` - `noCodeChangeCommentPath(runDir): string` - `writeNoCodeChangeCommentSignal(runDir, artifact)` — validate first, then write. - `readNoCodeChangeCommentSignal(runDir)` — returns `undefined` when the file is absent; throws `ArtifactValidationError` when content is malformed. - Export the filename constant, service functions, validator, and types from `src/artifacts/index.ts`. ## Acceptance Criteria - [ ] `validateNoCodeChangeCommentArtifact` accepts `{ issueKey: 'ABC-123', postedAt: '<ISO-8601>' }` and rejects missing/empty `issueKey`, missing/empty `postedAt`, and non-object input. - [ ] Write/read round-trip in a temp run dir returns the identical artifact. - [ ] Reading from a run dir without the file returns `undefined`. - [ ] Reading a malformed file throws `ArtifactValidationError`. - [ ] `NO_CODE_CHANGE_COMMENT_FILENAME === 'no-code-change-comment.json'` and `noCodeChangeCommentPath` places the file under the run dir. - [ ] All new symbols exported from `src/artifacts/index.ts`; unit tests in `src/artifacts/helpers/validateNoCodeChangeComment.test.ts` and `src/artifacts/services/noCodeChangeCommentArtifact.test.ts` pass. ## Test Plan - Targeted unit tests per above (temp run-dir fixtures): `npx vitest run src/artifacts/helpers/validateNoCodeChangeComment.test.ts src/artifacts/services/noCodeChangeCommentArtifact.test.ts` - `npm run lint` clean.

david added this to the No-code-change comment: core modules milestone

2026-09-05 18:35:02 +00:00

david added the

enhancement

label

2026-09-05 18:35:02 +00:00

david referenced this issue

2026-09-05 18:35:17 +00:00

postNoCodeChangeComment — deterministic post-and-mark service #305

david referenced this issue

2026-09-05 18:35:56 +00:00

Post the comment at runPipeline's no-code-change short-circuit #306