codeassembly-guidance 0.0.0 → 0.1.0
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/.meta/changelog.json +563 -0
- package/CHANGELOG.md +134 -0
- package/LICENSE +7 -0
- package/README.md +165 -1
- package/content/_partials/README.md +192 -0
- package/content/_partials/code-descriptions.md +4 -0
- package/content/_partials/code-style.md +7 -0
- package/content/_partials/comment-discipline.md +89 -0
- package/content/_partials/concision.md +3 -0
- package/content/_partials/diff-audit-checklist.md +9 -0
- package/content/_partials/file-access.md +4 -0
- package/content/_partials/live-repo-writes.md +13 -0
- package/content/_partials/plain-speech-calibration.md +66 -0
- package/content/_partials/plain-speech.md +13 -0
- package/content/_partials/prose-line-breaks.md +3 -0
- package/content/_partials/record-marker.md +1 -0
- package/content/_partials/reduced-object-relative.md +28 -0
- package/content/_partials/shell-commands.md +3 -0
- package/content/_partials/target-file-set-resolution.md +22 -0
- package/content/_partials/technical-recommendations.md +5 -0
- package/content/_partials/test-structure-audit-checklist.md +7 -0
- package/content/_partials/ticket-assessment-baseline.md +12 -0
- package/content/_partials/ticket-assessment.md +202 -0
- package/content/_partials/work-type-choice.md +13 -0
- package/content/codeassembly-content.yaml +49 -0
- package/content/collections/all.md +11 -0
- package/content/collections/atlassian.md +16 -0
- package/content/collections/recommended.md +34 -0
- package/content/collections/triage.md +77 -0
- package/content/collections/williamthorsen.md +25 -0
- package/content/guidance/README.md +22 -0
- package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
- package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
- package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
- package/content/guidance/rulebooks/accessibility-conventions.md +20 -0
- package/content/guidance/rulebooks/codeassembly-content-specification.md +161 -0
- package/content/guidance/rulebooks/command-output-conventions.md +14 -0
- package/content/guidance/rulebooks/commit-conventions.md +72 -0
- package/content/guidance/rulebooks/generated-content-policy.md +10 -0
- package/content/guidance/rulebooks/live-worktree-policy.md +18 -0
- package/content/guidance/rulebooks/readme-conventions.md +74 -0
- package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
- package/content/guidance/rulebooks/shell-conventions.md +279 -0
- package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +58 -0
- package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
- package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
- package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
- package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
- package/content/guidance/shared/AGENTS.md +43 -0
- package/content/scripts/README.md +41 -0
- package/content/scripts/describe-change.mjs +165 -0
- package/content/scripts/get-ticket-id.sh +131 -0
- package/content/scripts/manage-jira-ticket.mjs +209 -0
- package/content/scripts/resolve-frontmatter.sh +540 -0
- package/content/scripts/resolve-review-run.mjs +12 -0
- package/content/scripts/select-lede-exemplars.mjs +208 -0
- package/content/skills/_data/action-items.md +83 -0
- package/content/skills/_data/artifact-conventions.md +969 -0
- package/content/skills/_data/bitbucket-pr-access.md +89 -0
- package/content/skills/_data/branch-format.md +34 -0
- package/content/skills/_data/change-record.md +163 -0
- package/content/skills/_data/complexity-classification.md +58 -0
- package/content/skills/_data/concision.md +23 -0
- package/content/skills/_data/deployed-file-provenance.md +46 -0
- package/content/skills/_data/design-priorities.md +76 -0
- package/content/skills/_data/gh-body-file.md +30 -0
- package/content/skills/_data/git-commands.md +39 -0
- package/content/skills/_data/naming-conventions.md +50 -0
- package/content/skills/_data/pr-resolution.md +25 -0
- package/content/skills/_data/pr-source-resolution.md +36 -0
- package/content/skills/_data/recommendation-gradient.md +90 -0
- package/content/skills/_data/scope-and-deferral.md +83 -0
- package/content/skills/_data/spike-conventions.md +89 -0
- package/content/skills/_data/ticket-evaluation.md +13 -0
- package/content/skills/_data/ticket-id-extraction.md +43 -0
- package/content/skills/_data/ticket-source-resolution.md +147 -0
- package/content/skills/_data/title-templates.md +624 -0
- package/content/skills/_data/title-voice.md +17 -0
- package/content/skills/_data/work-types.json +168 -0
- package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
- package/content/skills/_partials/action-items.md +22 -0
- package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
- package/content/skills/_partials/commit-title-rendering.md +14 -0
- package/content/skills/_partials/gh-body-file.md +22 -0
- package/content/skills/_partials/nested-list-indent.md +9 -0
- package/content/skills/_partials/next-steps-after-plan.md +99 -0
- package/content/skills/_partials/next-steps-after-review.md +350 -0
- package/content/skills/_partials/option-format.md +84 -0
- package/content/skills/_partials/plan-template.md +97 -0
- package/content/skills/_partials/split-launch-prompts.md +5 -0
- package/content/skills/_partials/split-ticket-compose.md +5 -0
- package/content/skills/_partials/split-ticket-create.md +3 -0
- package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
- package/content/skills/_partials/ticket-concision.md +18 -0
- package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
- package/content/skills/_partials/ticket-placement.md +14 -0
- package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
- package/content/skills/_partials/ticket-skeleton.md +13 -0
- package/content/skills/add-change-record/SKILL.md +136 -0
- package/content/skills/add-test-ids/SKILL.md +51 -0
- package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
- package/content/skills/anti-patterns/SKILL.md +57 -0
- package/content/skills/assess-ticket/SKILL.md +46 -0
- package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
- package/content/skills/brainstorming/SKILL.md +107 -0
- package/content/skills/capture-event/SKILL.md +108 -0
- package/content/skills/capture-event/capture-event.mjs +216 -0
- package/content/skills/capture-feedback/SKILL.md +71 -0
- package/content/skills/capture-lede-decision/SKILL.md +163 -0
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
- package/content/skills/classify-complexity/SKILL.md +92 -0
- package/content/skills/collaborate/SKILL.md +86 -0
- package/content/skills/condense-branch/SKILL.md +83 -0
- package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
- package/content/skills/create-commit/SKILL.md +65 -0
- package/content/skills/create-devlog/SKILL.md +108 -0
- package/content/skills/create-gh-pr/SKILL.md +106 -0
- package/content/skills/create-pr/SKILL.md +150 -0
- package/content/skills/create-ticket/SKILL.md +350 -0
- package/content/skills/derive-session-context/derive-session-context.mjs +148 -0
- package/content/skills/design-and-plan/SKILL.md +194 -0
- package/content/skills/development-workflows/SKILL.md +41 -0
- package/content/skills/get-ticket-id/SKILL.md +67 -0
- package/content/skills/groom-backlog/SKILL.md +245 -0
- package/content/skills/groom-backlog/groom-backlog.mjs +106 -0
- package/content/skills/implement-plan/SKILL.md +164 -0
- package/content/skills/index-prototypes/SKILL.md +145 -0
- package/content/skills/index-prototypes/index-prototypes.mjs +328 -0
- package/content/skills/kb-add/SKILL.md +156 -0
- package/content/skills/kb-add/kb-add.mjs +216 -0
- package/content/skills/kb-curate/SKILL.md +117 -0
- package/content/skills/kb-curate/kb-curate.mjs +213 -0
- package/content/skills/kb-edit/SKILL.md +128 -0
- package/content/skills/kb-edit/kb-edit.mjs +219 -0
- package/content/skills/kb-retrieve/SKILL.md +100 -0
- package/content/skills/kb-retrieve/kb-retrieve.mjs +206 -0
- package/content/skills/kb-retrieve-events/SKILL.md +98 -0
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +206 -0
- package/content/skills/kb-update-events/SKILL.md +77 -0
- package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
- package/content/skills/merge-bb-pr/SKILL.md +136 -0
- package/content/skills/merge-gh-pr/SKILL.md +167 -0
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
- package/content/skills/merge-pr/SKILL.md +368 -0
- package/content/skills/migrate-feedback-memories/SKILL.md +136 -0
- package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
- package/content/skills/people-report/SKILL.md +208 -0
- package/content/skills/plan/SKILL.md +87 -0
- package/content/skills/prepare-prototype-brief/SKILL.md +126 -0
- package/content/skills/pull-from-backlog/SKILL.md +83 -0
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +208 -0
- package/content/skills/refine-plan/SKILL.md +259 -0
- package/content/skills/respond-to-review/SKILL.md +292 -0
- package/content/skills/review-bb-pr/SKILL.md +161 -0
- package/content/skills/review-branch/SKILL.md +301 -0
- package/content/skills/review-criteria/SKILL.md +108 -0
- package/content/skills/review-gh-pr/SKILL.md +155 -0
- package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
- package/content/skills/review-permissions/SKILL.md +39 -0
- package/content/skills/review-pr/SKILL.md +123 -0
- package/content/skills/revise-comments/SKILL.md +115 -0
- package/content/skills/revise-prose/SKILL.md +197 -0
- package/content/skills/revise-prose/revise-prose.mjs +229 -0
- package/content/skills/save-artifact/SKILL.md +69 -0
- package/content/skills/save-plan/SKILL.md +55 -0
- package/content/skills/software-engineering/SKILL.md +74 -0
- package/content/skills/streamline-guidance/SKILL.md +174 -0
- package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
- package/content/skills/summarize-change/SKILL.md +308 -0
- package/content/skills/summarize-chat/SKILL.md +100 -0
- package/content/skills/systematic-debugging/SKILL.md +308 -0
- package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
- package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
- package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
- package/content/skills/systematic-debugging/find-polluter.sh +68 -0
- package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
- package/content/skills/systematic-debugging/test-academic.md +16 -0
- package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
- package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
- package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
- package/content/skills/testing-conventions/SKILL.md +168 -0
- package/content/skills/testing-conventions/mistakes.md +1 -0
- package/content/skills/typescript-testing-conventions/SKILL.md +129 -0
- package/content/skills/update-jira-ticket/SKILL.md +245 -0
- package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
- package/content/skills/update-project-guidance/SKILL.md +300 -0
- package/content/skills/upgrade-dependencies/SKILL.md +139 -0
- package/content/skills/wrap-up/SKILL.md +431 -0
- package/content/subagents/_data/claude.yaml +19 -0
- package/content/subagents/_data/rovo.yaml +31 -0
- package/content/subagents/canary.md +11 -0
- package/content/subagents/entry-drafter.md +187 -0
- package/content/subagents/handoff-reviewer.md +75 -0
- package/content/subagents/plan-reviewer.md +184 -0
- package/content/subagents/plan-reviser.md +88 -0
- package/content/subagents/prose-reviser.md +130 -0
- package/content/subagents/ticket-assessor.md +139 -0
- package/package.json +70 -2
- package/schemas/preferences.v1.json +294 -0
- package/schemas/work-types.v1.json +142 -0
|
@@ -0,0 +1,168 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: testing-conventions
|
|
3
|
+
description: Test naming conventions and behavioral testing patterns for projects with test suites
|
|
4
|
+
user-invocable: false
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Testing conventions
|
|
8
|
+
|
|
9
|
+
## What a test is for
|
|
10
|
+
|
|
11
|
+
A test guards a behavior against accidental breakage. A **behavior** is an outcome that a caller or a user relies on: what a function returns, what a user can do, what the system refuses. A **value** is a thing that the code contains today while producing it: the text of a message, the contents of a config, the members of a list. A test that pins a value fails on every intended change to that value and catches nothing, so each such change is made twice.
|
|
12
|
+
|
|
13
|
+
Before writing a test, ask what would go uncaught if it did not exist. Three answers rule the test out.
|
|
14
|
+
|
|
15
|
+
- **A change that someone would have to make on purpose.** Rewording a message, editing a config, adding a member to a list: Each is a decision, and review already guards decisions. A test is justified when it catches an accident, a change made without intending to touch this outcome, such as a route added without its guard or a refactor that drops a case. A scenario constructed so that the test has something to catch is not an accident.
|
|
16
|
+
- **Nothing that this repository authored.** Machine state, the user's environment, and a dependency's behavior are not under test, and enabling a dependency's feature does not make that feature's behavior ours. If the right response to red would be a bug report upstream, the test is not ours.
|
|
17
|
+
- **A difference that costs nothing until noticed.** A relaxed lint rule, a setting that drifts from its best value, a directory that departs from convention: A standing test costs more than the moment that it saves. A caught failure has to cost more than noticing it: a wrong answer returned, a task that a user cannot finish, data lost or exposed.
|
|
18
|
+
|
|
19
|
+
Then ask where the expected result comes from. A specification, a format, or a rule that someone could state without opening the code makes it an expectation. If pasting in whatever the code now produces would make the test pass again, the test pins a value, whatever its name says. When a test compares two sets, derive the expected one from its source; a set typed into the test drifts.
|
|
20
|
+
|
|
21
|
+
Three cases recur. Configuration is verified by the tool that reads it, which the build and lint gates run; if an accident is real and the tool is silent, prevent it at the tool rather than detect it in a test. Wording is asserted only when the text is the sole thing that distinguishes two code paths that exist, and then by a durable fragment. A process that this repository does not author is replaced by a stub.
|
|
22
|
+
|
|
23
|
+
If a rule above forbids a test and the case seems exceptional, stop before writing it, state the case in one sentence, and wait.
|
|
24
|
+
|
|
25
|
+
## When tests are required
|
|
26
|
+
|
|
27
|
+
Every change to a behavior, as defined above, is covered by a test. A change that does not add runtime behavior does not need a new test: a deletion, a type consumed only within this compile, prose, styling.
|
|
28
|
+
|
|
29
|
+
A test that guards a behavior still has to clear two checks:
|
|
30
|
+
|
|
31
|
+
1. **Nothing else fails first.** If the compiler, the linter, or a gate that already reproduces the failure condition on every run would catch the regression, that gate is the guard, and a narrower test is a weaker and more brittle duplicate. A gate that merely exercises the same area does not qualify; it has to reproduce the condition.
|
|
32
|
+
2. **It would catch the failure that it guards against.** Run it against what it rejects: Break the guarded thing, watch the test fail, restore it. A test that still passes is not a guard. If reaching the cause means replicating a dependency's private shape, the test breaks or silently stops testing at the next upgrade.
|
|
33
|
+
|
|
34
|
+
If a change needs coverage and these sections rule out every candidate test, it is merged without one; say which answer ruled the candidate out.
|
|
35
|
+
|
|
36
|
+
## Do not test that removed things stay removed
|
|
37
|
+
|
|
38
|
+
This is the commonest test that guards a decision. When a change removes code, text, or behavior, never add a permanent test asserting the removed thing is absent (a `not.toContain` guard against a deleted string, `expect(isEventType('input.received')).toBe(false)` against a removed variant). The assertion encodes history, not contract: It can fail only if someone reverts that exact line, so it does not guard any regression class, and such assertions accumulate without limit. The positive assertion describing the replacement behavior is the real guard.
|
|
39
|
+
|
|
40
|
+
Diagnostic: Would this test exist if the deleted code had never existed? If no, don't write it.
|
|
41
|
+
|
|
42
|
+
Verify the removal is complete once, as a pre-merge check (a `grep`, a plan Verification step), not a standing test. This applies to any change that removes something, not only removal-only changes.
|
|
43
|
+
|
|
44
|
+
When a test guards that a set is closed, the witness is an arbitrary non-member, never a member that was removed. The removed name guards nothing that the arbitrary one does not, and it records history.
|
|
45
|
+
|
|
46
|
+
## Loosen a test broken by a wording-only change
|
|
47
|
+
|
|
48
|
+
When a wording-only change forces a test update, don't re-pin the new wording: Match just the part that identifies the behavior, or drop the assertion if the behavior does not depend on the text.
|
|
49
|
+
|
|
50
|
+
## Naming of tests
|
|
51
|
+
|
|
52
|
+
**Always** use test names that describe the specific behavior being tested.
|
|
53
|
+
**Never** use vague or meaningless terms.
|
|
54
|
+
|
|
55
|
+
### Avoid these meaningless patterns
|
|
56
|
+
|
|
57
|
+
- ❌ **"handles X"**: Too vague, doesn't describe what happens
|
|
58
|
+
- ❌ **"does X correctly"**: Meaningless (all tests verify correctness)
|
|
59
|
+
- ❌ **"works with Y"**: Doesn't specify the expected outcome
|
|
60
|
+
- ❌ **"processes Z properly"**: "Properly" is subjective and unclear
|
|
61
|
+
|
|
62
|
+
### Use specific behavioral descriptions
|
|
63
|
+
|
|
64
|
+
- ✅ **"returns 0 when map is empty"**: Clear condition and outcome
|
|
65
|
+
- ✅ **"throws error for invalid input"**: Specific behavior under specific condition
|
|
66
|
+
- ✅ **"preserves existing data when adding new item"**: Describes what remains unchanged
|
|
67
|
+
- ✅ **"removes only items matching criteria"**: Specifies selective behavior
|
|
68
|
+
|
|
69
|
+
### Test name formula
|
|
70
|
+
|
|
71
|
+
Use this pattern: `"when/if [condition], [action/outcome]"`
|
|
72
|
+
|
|
73
|
+
Examples:
|
|
74
|
+
|
|
75
|
+
- `"if no items match filter, returns empty array"`
|
|
76
|
+
- `"if email format is invalid, throws ValidationError"`
|
|
77
|
+
- `"when saving user preferences, updates timestamp"`
|
|
78
|
+
- `"preserves order when removing middle element"`
|
|
79
|
+
|
|
80
|
+
### What makes a good test name
|
|
81
|
+
|
|
82
|
+
1. **Specific**: Describes exact behavior, not general capability
|
|
83
|
+
2. **Conditional**: States the circumstances that trigger the behavior
|
|
84
|
+
3. **Outcome-focused**: What happens, not just that something happens
|
|
85
|
+
4. **Readable**: Anyone can understand the test purpose without reading the code
|
|
86
|
+
|
|
87
|
+
<!-- include: ../../_partials/comment-discipline.md / -->
|
|
88
|
+
|
|
89
|
+
## Comments in test files
|
|
90
|
+
|
|
91
|
+
The same rules apply to test files as to source. Test names already communicate intent and assertions communicate the check, so everything outside the test-comment carve-out is over-commenting.
|
|
92
|
+
|
|
93
|
+
## Test structure
|
|
94
|
+
|
|
95
|
+
Tests should make their variation easy to see. When N adjacent tests differ only in one input but share a large block of identical setup, the reader has to diff three or four nearly-identical render calls to find what's actually being tested. The fix is not "delete things"; it's "factor the shared part out so that the variation reads as variation."
|
|
96
|
+
|
|
97
|
+
This is the same signal-buried-in-noise failure mode that [comment discipline](#comment-discipline) addresses on the comment side. Different mechanism, same principle.
|
|
98
|
+
|
|
99
|
+
### Rules
|
|
100
|
+
|
|
101
|
+
1. **Test bodies should be mostly variation and assertion, not setup.** Any prop, fixture, or boilerplate identical across N adjacent tests is noise. Factor it into a default-bearing helper, or collapse the tests into a single parameterized test in which the variation reads as a table.
|
|
102
|
+
2. **Use `it.each` when N adjacent tests differ only in a small set of inputs and the body is structurally identical.** Use a named helper when the variation is bigger, when shared setup should move into a helper signature, or when assertion shapes differ per case.
|
|
103
|
+
3. **Test the rule, not the data.** Prefer counts, predicates, and structural assertions (`expect(getVisibleChipCount()).toBe(N)`, `expect(queryPillElement()).toBeInTheDocument()`) over enumerating specific fixture labels in every row. Assert specific data flow _once_, in a focused test, not per row of a table.
|
|
104
|
+
|
|
105
|
+
### Diagnostic
|
|
106
|
+
|
|
107
|
+
Before writing a third test in the same `describe` block, scan the previous two: How many tokens does a reader have to diff to find what's actually different between them? If the answer is more than a handful, the signal is buried. Parameterize the trio or extract a helper before continuing.
|
|
108
|
+
|
|
109
|
+
### When N copies are right
|
|
110
|
+
|
|
111
|
+
The smell is shared _setup with one variable_, not shared _shape with different intents_. Three tests that read as genuinely distinct behavioral claims should stay as three `it` blocks even if their bodies superficially resemble each other. Do not collapse distinct intents into a table.
|
|
112
|
+
|
|
113
|
+
### Audit before save
|
|
114
|
+
|
|
115
|
+
<!-- include: ../../_partials/test-structure-audit-checklist.md / -->
|
|
116
|
+
|
|
117
|
+
## Test organization
|
|
118
|
+
|
|
119
|
+
- **Use function/class reference as describe argument**: `describe(myFunction, ...)` instead of `describe('myFunction', ...)`
|
|
120
|
+
|
|
121
|
+
### Test file length
|
|
122
|
+
|
|
123
|
+
A test file runs in one test worker, and a file that keeps its fixtures makes an append cheaper than a split, so a file grows until it is the slowest unit in the suite. Before adding tests to a file that the addition would leave past the ceiling, split the file by aspect, then add the tests to the file that their aspect names.
|
|
124
|
+
|
|
125
|
+
- **Ceiling.** The `max-lines` setting that the project's lint configuration applies to test files. Where the lint does not set one, 500 lines, counting every line.
|
|
126
|
+
- **Aspect.** A group of the subject's behaviors that shares setup and reads without the rest of the file. Each split file contains one aspect.
|
|
127
|
+
- **Naming.** Each split file keeps the subject's name and adds the aspect after it, followed by any segment that the project's naming requires: `sync.test.ts` becomes `sync.retirement.test.ts`, and `sync.tool.test.ts` becomes `sync.retirement.tool.test.ts`.
|
|
128
|
+
- **Fixtures.** Move the fixture builders that the split files share out of the test files, into a module in a `test-utils/` directory beside the tests (beside `__tests__/` when the tests live in one, never inside it), so that a new aspect file costs one import.
|
|
129
|
+
|
|
130
|
+
## Keep passing tests quiet
|
|
131
|
+
|
|
132
|
+
A passing test prints nothing beyond the runner's report. Output that the code under test writes to the console, stdout, or stderr during a passing run sits between the results, and it hides the warning or stack trace that matters when a run fails.
|
|
133
|
+
|
|
134
|
+
When the code under test writes output, intercept it in the test that triggers it, and restore it when that test ends:
|
|
135
|
+
|
|
136
|
+
- **Capture** the output when it is the behavior, such as a CLI's report or a warning on which a caller relies, and assert on a durable fragment of it, as [What a test is for](#what-a-test-is-for) states for wording.
|
|
137
|
+
- **Silence** the output when it is incidental to the behavior under test.
|
|
138
|
+
|
|
139
|
+
Intercept only the channels that the test expects to fire. A silencer installed for a whole file or suite, or one that covers every channel, hides the unexpected output that this rule exists to surface.
|
|
140
|
+
|
|
141
|
+
The `typescript-testing-conventions` skill names the TypeScript techniques.
|
|
142
|
+
|
|
143
|
+
## Mocking principles
|
|
144
|
+
|
|
145
|
+
Mock only what matters in component tests. Don't forward irrelevant props or replicate complex implementation details.
|
|
146
|
+
|
|
147
|
+
```typescript
|
|
148
|
+
// ✅ Good: Focused on test needs
|
|
149
|
+
jest.mock('@atlaskit/component', () => ({
|
|
150
|
+
Component: ({ children, isOpen }: Props) =>
|
|
151
|
+
isOpen ? <div data-testid="component">{children}</div> : null
|
|
152
|
+
}));
|
|
153
|
+
|
|
154
|
+
// ❌ Avoid: Unnecessary complexity
|
|
155
|
+
jest.mock('@atlaskit/component', () => ({
|
|
156
|
+
Component: ({ children, isOpen, width, onClose, ...props }: ComplexProps) =>
|
|
157
|
+
<div {...props} style={{ width }}>{isOpen && children}</div>
|
|
158
|
+
}));
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
## Additional patterns
|
|
162
|
+
|
|
163
|
+
### Omit "should" from test names
|
|
164
|
+
|
|
165
|
+
Describe what the code actually does when the test passes:
|
|
166
|
+
|
|
167
|
+
- ✅ "returns false for unknown gates"
|
|
168
|
+
- ❌ "should return false for unknown gates"
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
- 2026-04-16: Wrote integration test that ran a full vitest suite as a side effect just to verify a log message prefix, then proposed increasing the timeout instead of questioning the design → Skill should state: Tests must do the minimum work needed to verify the behavior under test; use lightweight fixtures (e.g., temp directories with trivial scripts) instead of exercising real heavyweight operations. Treat timeout increases as a red flag that the test is doing unnecessary work, not as a solution.
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: typescript-testing-conventions
|
|
3
|
+
description: TypeScript testing patterns with proper assertions and type narrowing for Vitest- and Jest-based projects
|
|
4
|
+
user-invocable: false
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# TypeScript testing rules
|
|
8
|
+
|
|
9
|
+
Rules for writing robust, maintainable tests in TypeScript projects.
|
|
10
|
+
|
|
11
|
+
## Test structure
|
|
12
|
+
|
|
13
|
+
### Never use conditional expect statements
|
|
14
|
+
|
|
15
|
+
**❌ Incorrect: Conditional expects**
|
|
16
|
+
|
|
17
|
+
```typescript
|
|
18
|
+
it('should handle optional values', () => {
|
|
19
|
+
const result = someFunction();
|
|
20
|
+
|
|
21
|
+
if (result) {
|
|
22
|
+
expect(result.value).toBe('expected');
|
|
23
|
+
expect(result.status).toBe('success');
|
|
24
|
+
}
|
|
25
|
+
});
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
**✅ Correct: Use runtime assertions**
|
|
29
|
+
|
|
30
|
+
```typescript
|
|
31
|
+
import { assert } from '~src/utils/types/type-guards';
|
|
32
|
+
|
|
33
|
+
it('should handle optional values', () => {
|
|
34
|
+
const result = someFunction();
|
|
35
|
+
|
|
36
|
+
assert(result, 'Function should return a result');
|
|
37
|
+
expect(result.value).toBe('expected');
|
|
38
|
+
expect(result.status).toBe('success');
|
|
39
|
+
});
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
### Why conditional expects are problematic
|
|
43
|
+
|
|
44
|
+
1. **Silent failures**: If condition is false, the test does not run any assertions and passes incorrectly
|
|
45
|
+
2. **Unclear intent**: Ambiguous whether condition failing should pass or fail
|
|
46
|
+
3. **Reduced coverage**: Conditional paths may not be tested consistently
|
|
47
|
+
4. **Debugging difficulty**: Hard to determine why a test passed when it should have failed
|
|
48
|
+
|
|
49
|
+
### Use runtime assertions for type narrowing
|
|
50
|
+
|
|
51
|
+
**✅ Preferred patterns**
|
|
52
|
+
|
|
53
|
+
```typescript
|
|
54
|
+
// For nullable values
|
|
55
|
+
assert(value !== null, 'Value should not be null');
|
|
56
|
+
expect(value.property).toBe('expected');
|
|
57
|
+
|
|
58
|
+
// For optional properties
|
|
59
|
+
assert(obj.optionalProp, 'Optional property should be defined');
|
|
60
|
+
expect(obj.optionalProp.nested).toBe('value');
|
|
61
|
+
|
|
62
|
+
// For array length
|
|
63
|
+
assert(array.length > 0, 'Array should not be empty');
|
|
64
|
+
expect(array[0]).toBe('first item');
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## Test reliability
|
|
68
|
+
|
|
69
|
+
### Every test should have deterministic assertions
|
|
70
|
+
|
|
71
|
+
- Each test should always run the same number of assertions
|
|
72
|
+
- Use `assert()` or similar runtime guards to ensure preconditions
|
|
73
|
+
- Fail fast with clear error messages when preconditions aren't met
|
|
74
|
+
|
|
75
|
+
### Prefer explicit failure over silent success
|
|
76
|
+
|
|
77
|
+
```typescript
|
|
78
|
+
// ❌ May silently pass if array is empty
|
|
79
|
+
if (results.length > 0) {
|
|
80
|
+
expect(results[0]).toBe('expected');
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
// ✅ Explicitly fails if array is empty
|
|
84
|
+
assert(results.length > 0, 'Results array should not be empty');
|
|
85
|
+
expect(results[0]).toBe('expected');
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
## Type safety in tests
|
|
89
|
+
|
|
90
|
+
- Import and use project-specific assertion utilities
|
|
91
|
+
- Use TypeScript's type narrowing after assertions
|
|
92
|
+
- Ensure tests fail clearly when type assumptions are violated
|
|
93
|
+
|
|
94
|
+
```typescript
|
|
95
|
+
import { assert, assertIsNonNullable } from '~src/utils/types/type-guards';
|
|
96
|
+
|
|
97
|
+
it('processes user data correctly', () => {
|
|
98
|
+
const user = getUserData();
|
|
99
|
+
|
|
100
|
+
assertIsNonNullable(user, 'User data should be available');
|
|
101
|
+
// TypeScript now knows user is non-null
|
|
102
|
+
expect(user.name).toBe('John Doe');
|
|
103
|
+
});
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
## Console and stream output
|
|
107
|
+
|
|
108
|
+
The `testing-conventions` skill states the rule: A passing test prints nothing beyond the runner's report. These are the TypeScript techniques for applying it. Each helper restores what it replaced when its `using` scope ends.
|
|
109
|
+
|
|
110
|
+
- **Console calls under Vitest:** `silenceConsole` from `@williamthorsen/toolbelt.vitest/candidate` silences the named console methods and returns a spy for each one. To assert on the output, pass a spy to `listConsoleLines` from the same module, which returns one line per call.
|
|
111
|
+
- **Rendered stream output:** `captureStdio` from `@williamthorsen/toolbelt.testing/candidate` buffers what is written to stdout and stderr, including format specifiers and inspected objects. Pass `includeConsole: true` when the code reports through `console`.
|
|
112
|
+
|
|
113
|
+
```typescript
|
|
114
|
+
import { listConsoleLines, silenceConsole } from '@williamthorsen/toolbelt.vitest/candidate';
|
|
115
|
+
|
|
116
|
+
it('if a deprecated option is passed, warns once', () => {
|
|
117
|
+
using silent = silenceConsole(['warn']);
|
|
118
|
+
parseOptions({ legacy: true });
|
|
119
|
+
expect(listConsoleLines(silent.warn)).toStrictEqual([expect.stringContaining('deprecated')]);
|
|
120
|
+
});
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Where the project does not depend on these packages, spy on the method with the runner, and restore the spy in `afterEach` or through the runner's `restoreMocks` option:
|
|
124
|
+
|
|
125
|
+
```typescript
|
|
126
|
+
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
Under Jest, `jest.spyOn` takes the same form.
|
|
@@ -0,0 +1,245 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: update-jira-ticket
|
|
3
|
+
description: 'Use whenever creating or updating a Jira issue description or comment, whether through acli, a contentFormat-based tool (createJiraIssue taking description, editJiraIssue taking fields.description, both with contentFormat markdown/adf), or an HTML-based tool (create_jira_issue / update_jira_issue, taking description_html / comment_html). Jira stores a Markdown or HTML body with its task-list syntax escaped, so checklists go in as plain bullets on those surfaces and as real task items through acli. The HTML tools additionally need the bundled pre-flight checker to catch INVALID_INPUT triggers (composition rules, named entities, Confluence macros, multi-line <pre>, disallowed elements) before any MCP round-trip; the contentFormat tools take Markdown directly, and acli takes plain text or ADF and parses Markdown as wiki markup.'
|
|
4
|
+
user-invocable: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Update Jira ticket
|
|
8
|
+
|
|
9
|
+
The same constraint applies to creating a Jira issue and to updating one: Whatever the client, what you submit is stored as Atlassian Document Format (ADF). What differs is the format that the client takes, and there are three of them. `acli` takes ADF, the `contentFormat` tools take Markdown, and the HTML tools take HTML that Jira converts for you, a conversion that frequently rejects valid-looking HTML with an opaque `INVALID_INPUT` error. Read the checklist rule below, identify your client, then follow its path.
|
|
10
|
+
|
|
11
|
+
## Checklists
|
|
12
|
+
|
|
13
|
+
Convert task-list syntax (`- [ ]` / `- [x]`) to plain `-` bullets before submitting Markdown or HTML, on creation and update alike. Neither conversion to ADF maps it to task items: The brackets are escaped, so the line persists as a bullet reading `\[ \] ...`.
|
|
14
|
+
|
|
15
|
+
Native checkboxes exist only as ADF `taskList` / `taskItem` nodes, which makes the [ADF path](#adf-path) the one exception. A body submitted as ADF contains real task items and keeps them. That is not a reason to use ADF elsewhere: Because `contentFormat` applies to the whole field rather than a section of it, a checklist never justifies authoring an entire description as ADF on a client that takes Markdown.
|
|
16
|
+
|
|
17
|
+
Artefact-sourced content is in scope, and it is the most common source of unconverted task-list syntax: The ticket-artefact templates of `design-and-plan` and `create-ticket` write acceptance criteria as `- [ ]` checkboxes. A body forwarded verbatim from such an artefact contains them.
|
|
18
|
+
|
|
19
|
+
## Identify your client
|
|
20
|
+
|
|
21
|
+
Match your client to one of these shapes:
|
|
22
|
+
|
|
23
|
+
- **`acli`**: `acli jira workitem create` / `acli jira workitem edit`, whose `--description` and `--description-file` are documented as plain text or ADF. A Markdown body is not merely left unrendered there: It is parsed as Jira wiki markup, so headings become nested ordered list items and punctuation comes back backslash-escaped. → Follow the [ADF path](#adf-path).
|
|
24
|
+
- **`contentFormat`-based tool**, e.g. `createJiraIssue` / `editJiraIssue` (Atlassian Rovo): Takes the description together with `contentFormat: "markdown" | "adf"` -- top-level on `createJiraIssue`, under `fields` on `editJiraIssue`. No HTML surface. → Follow the [Markdown path](#markdown-path).
|
|
25
|
+
- **`description_html`-based tool**: `create_jira_issue` / `update_jira_issue` with `description_html` / `comment_html`. → Follow the [HTML path](#html-path).
|
|
26
|
+
|
|
27
|
+
If more than one is available, prefer the `contentFormat` tool: It takes Markdown directly, whereas `acli` needs ADF. Because the `contentFormat` tool needs a connected Jira server, `acli` is the fallback for a machine without one.
|
|
28
|
+
|
|
29
|
+
## ADF path
|
|
30
|
+
|
|
31
|
+
Use this branch when the client is `acli`.
|
|
32
|
+
|
|
33
|
+
1. **Author Markdown, then convert it to ADF with the helper.** Prefer a local Markdown artefact when one exists; otherwise compose in Markdown and write it to a scratch file. Then run:
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
node {harness_home_dir}/scripts/manage-jira-ticket.mjs convert-body --body-file {absolute Markdown path} --out {absolute ADF path}
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Pass both paths as literal absolute paths, unquoted; the helper refuses a missing or empty body file. It writes the ADF document to `--out` and prints `{"adfPath": "..."}`. Pass that path to `--description-file`, or to `--body-file` for a comment. Never hand-write the ADF.
|
|
40
|
+
|
|
41
|
+
2. **Never pass Markdown to `--description` or `--description-file`.** `acli` parses it as Jira wiki markup, in which `#` opens an ordered list, so `## Problem` becomes a nested numbered item and every backtick, tilde, underscore, and bracket comes back backslash-escaped. Because the command reports success, only reading the work item back reveals the damage.
|
|
42
|
+
3. **Reserve plain text for a body without any structure to lose**, such as a one-line comment. Submit anything containing headings, lists, or inline marks as ADF.
|
|
43
|
+
4. **Keep your checkboxes**, per [Checklists](#checklists). The helper converts task-list syntax to `taskList` / `taskItem` nodes, so leave it in the Markdown rather than flattening it to plain bullets.
|
|
44
|
+
5. **Do not sanitize.** The HTML allowlist, the composition rules, and the pre-flight checker under [HTML path](#html-path) **do not apply** here, and you must **not** run `update-jira-ticket.mjs`, the HTML checker. `manage-jira-ticket.mjs` is the converter.
|
|
45
|
+
|
|
46
|
+
## Markdown path
|
|
47
|
+
|
|
48
|
+
Use this branch when the client is a `contentFormat`-based tool (e.g. `createJiraIssue` / `editJiraIssue`).
|
|
49
|
+
|
|
50
|
+
1. **Author Markdown.** Prefer a local Markdown artefact when one exists; otherwise compose in Markdown. Pass it via `contentFormat: "markdown"`.
|
|
51
|
+
2. **Prefer Markdown over ADF.** Reserve `contentFormat: "adf"` for content that Markdown cannot represent faithfully (panels, status lozenges, expand blocks, layout columns). ADF is full-fidelity JSON but verbose and harder to author, so use it only when Markdown genuinely falls short.
|
|
52
|
+
3. **Write checklists as plain bullets**, per [Checklists](#checklists).
|
|
53
|
+
4. **Do not sanitize.** The HTML allowlist, the composition rules, and the pre-flight checker under [HTML path](#html-path) **do not apply** here, and you must **not** run `update-jira-ticket.mjs`.
|
|
54
|
+
|
|
55
|
+
That is the whole of both non-HTML branches. Those rules exist solely to prevent failures in Jira's HTML→ADF conversion, which is never invoked when you submit ADF or Markdown, so everything under [HTML path](#html-path) is irrelevant on either path, and rendering content to allowlist HTML to run the checker over it is wasted work.
|
|
56
|
+
|
|
57
|
+
## HTML path
|
|
58
|
+
|
|
59
|
+
Use this branch only when the available tool is the HTML-surface `create_jira_issue` / `update_jira_issue` (with `description_html` or `comment_html`). The MCP tool advertises a permissive HTML surface, but the payload is converted to Atlassian Document Format (ADF) before persistence, and that conversion frequently rejects valid-looking HTML with an opaque `INVALID_INPUT` error. This branch prescribes the one path that avoids the known triggers, backed by a deterministic pre-flight checker.
|
|
60
|
+
|
|
61
|
+
### The correct path for the HTML tool
|
|
62
|
+
|
|
63
|
+
1. **Source content as Markdown.** Prefer a local Markdown artefact when one exists. Otherwise, compose in Markdown first; never author HTML directly.
|
|
64
|
+
2. **Convert Markdown to HTML using only the allowlist below.** Anything outside the allowlist must be omitted or rewritten. Task-list syntax becomes a plain `<li>`, which is how [Checklists](#checklists) renders on this path; never pass the brackets through as literal text.
|
|
65
|
+
3. **Run the pre-flight checker against the rendered HTML.** Fix everything it flags, then re-run until it returns `ok: true`. See [Pre-flight checker](#pre-flight-checker) for the contract.
|
|
66
|
+
4. **Pass the HTML inline** to `description_html` or `comment_html`.
|
|
67
|
+
5. **Never pass a file path** to `description_html` / `comment_html`. File-path mode is forbidden: It has been observed to fail with `INVALID_INPUT`.
|
|
68
|
+
6. **Never include `version_message`** as an argument. It is not a parameter of `create_jira_issue` or `update_jira_issue`; including it triggers a validation failure and a wasted retry.
|
|
69
|
+
|
|
70
|
+
### Pre-flight checker
|
|
71
|
+
|
|
72
|
+
A bundled helper at `{harness_home_dir}/skills/update-jira-ticket/update-jira-ticket.mjs` validates the rendered HTML against every known failure class. The agent invokes it before every `create_jira_issue` / `update_jira_issue` call.
|
|
73
|
+
|
|
74
|
+
#### Invocation
|
|
75
|
+
|
|
76
|
+
Pipe the HTML on stdin; the helper writes a JSON result to stdout and exits 0 in both the pass and fail cases (only invocation errors exit non-zero).
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
cat <<'EOF' | node {harness_home_dir}/skills/update-jira-ticket/update-jira-ticket.mjs
|
|
80
|
+
<p>Your rendered HTML payload here.</p>
|
|
81
|
+
EOF
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
#### Output
|
|
85
|
+
|
|
86
|
+
`ok: true` means the payload passes every rule:
|
|
87
|
+
|
|
88
|
+
```json
|
|
89
|
+
{ "ok": true }
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
`ok: false` includes a `findings` array. Each finding identifies the rule, the offending source snippet, the 1-based line (when derivable), and a suggested fix:
|
|
93
|
+
|
|
94
|
+
```json
|
|
95
|
+
{
|
|
96
|
+
"ok": false,
|
|
97
|
+
"findings": [
|
|
98
|
+
{
|
|
99
|
+
"rule": "composition-code-inline-mark",
|
|
100
|
+
"snippet": "<strong>...<code>",
|
|
101
|
+
"line": 12,
|
|
102
|
+
"fix": "Move the <code> outside <strong>, or drop the inline mark."
|
|
103
|
+
}
|
|
104
|
+
]
|
|
105
|
+
}
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
The rule classes are: `composition-code-inline-mark`, `named-entity`, `confluence-construct`, `pre-multiline`, `disallowed-element`. The checker may report multiple findings for the same payload; fix them all before the next MCP attempt.
|
|
109
|
+
|
|
110
|
+
#### Acting on findings
|
|
111
|
+
|
|
112
|
+
For each finding, apply the suggested fix to the source. Do not invoke `create_jira_issue` / `update_jira_issue` until the checker returns `ok: true`. Findings are not optional: Every rule corresponds to a documented `INVALID_INPUT` trigger.
|
|
113
|
+
|
|
114
|
+
### Allowed elements
|
|
115
|
+
|
|
116
|
+
Exhaustive list. Nothing else.
|
|
117
|
+
|
|
118
|
+
`h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `p`, `ul`, `ol`, `li`, `strong`, `em`, `code`, `a`, `blockquote`, `hr`, `br`, `table`, `thead`, `tbody`, `tr`, `th`, `td`
|
|
119
|
+
|
|
120
|
+
**Always strip `<ac:*>` and `<ri:*>` constructs unconditionally.** These are Confluence storage-format extensions: `<ac:*>` for Confluence elements like task lists and structured macros (e.g., `<ac:task-list>`, `<ac:structured-macro>`); `<ri:*>` for resource identifiers (e.g., `<ri:user>`, `<ri:page>`, `<ri:attachment>`). They do not have a Jira analogue, and including them produces `INVALID_INPUT`. If you have been working with Confluence content in the same session, audit the payload before sending; the checker will flag any that remain.
|
|
121
|
+
|
|
122
|
+
### Composition rules (reference)
|
|
123
|
+
|
|
124
|
+
The pre-flight checker enforces these; this section explains why they exist.
|
|
125
|
+
|
|
126
|
+
#### `<code>` combined with other inline marks
|
|
127
|
+
|
|
128
|
+
`<code>` may not nest with `<strong>`, `<em>`, `<a>`, `<strike>`, `<u>`, `<sub>`, or `<sup>` in either direction. ADF represents inline styling as marks on text nodes, and the `code` mark is mutually exclusive with the other inline marks. Applying styling to monospace code does not have a defensible rendering anyway: Code is meant to display literal characters.
|
|
129
|
+
|
|
130
|
+
**Workaround:** Move the `<code>` outside the styling wrapper so that the two apply to different text runs, or drop the styling entirely.
|
|
131
|
+
|
|
132
|
+
```html
|
|
133
|
+
<!-- Wrong -->
|
|
134
|
+
<strong><code>isDevMode</code> parameter</strong>
|
|
135
|
+
|
|
136
|
+
<!-- Right (separate text runs) -->
|
|
137
|
+
<strong>The </strong><code>isDevMode</code><strong> parameter</strong>
|
|
138
|
+
|
|
139
|
+
<!-- Also right (drop the styling) -->
|
|
140
|
+
<code>isDevMode</code> parameter
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
#### Multi-line code samples
|
|
144
|
+
|
|
145
|
+
`<pre>` is omitted from the allowlist entirely, and the checker also flags multi-line `<pre>` separately. ADF's `codeBlock` node accepts plain text, but the converter mishandles the combination of newlines and quote characters inside the `pre` block. The converter handles the same characters correctly in inline `<code>` inside `<p>`, so the `<pre>` wrapper is the differentiator.
|
|
146
|
+
|
|
147
|
+
**Workaround:** Render multi-line code as either multiple `<p><code>...</code></p>` paragraphs (one per logical line) or a single `<p>` with `<br>` separators between lines and inline `<code>` wrapping the code on each line. Single-line code is unchanged; continue to use inline `<code>` inside `<p>` or `<li>` as usual.
|
|
148
|
+
|
|
149
|
+
### Character handling
|
|
150
|
+
|
|
151
|
+
Use **literal Unicode** in HTML. Do not use named HTML entities outside the three universally-safe ones. The checker flags any named entity other than `&`, `<`, `>` in text content.
|
|
152
|
+
|
|
153
|
+
| Don't write | Write instead |
|
|
154
|
+
| ----------- | ------------------------ |
|
|
155
|
+
| `—` | `—` (U+2014) |
|
|
156
|
+
| `–` | `–` (U+2013) |
|
|
157
|
+
| `…` | `…` (U+2026) |
|
|
158
|
+
| ` ` | regular space, or U+00A0 |
|
|
159
|
+
| `©` | `©` (U+00A9) |
|
|
160
|
+
| `’` | `'` (U+2019) |
|
|
161
|
+
|
|
162
|
+
`"` and `'` are valid only inside attribute values in which they're needed to avoid clashing with the attribute's quote style. The checker only scans text content for named entities, so legitimate attribute-value uses are not flagged.
|
|
163
|
+
|
|
164
|
+
### Recovery protocol (backstop)
|
|
165
|
+
|
|
166
|
+
Use only if `INVALID_INPUT` still fires after the pre-flight checker returned `ok: true`. A clean checker result followed by an MCP rejection means the payload triggered an unknown failure class that the checker does not yet catch.
|
|
167
|
+
|
|
168
|
+
#### 1. Report the failure to the user
|
|
169
|
+
|
|
170
|
+
Do not create a probe ticket silently. Present the situation to the user and let them choose how to proceed. Use the [option format](#option-format):
|
|
171
|
+
|
|
172
|
+
> Jira rejected this payload and the pre-flight checker did not find any known issues. This is likely a new failure class. Only option 1 identifies it, which a fix or a new checker rule needs, and it does so by creating a real ticket tagged `mcp-probe` that has to be deleted afterward. How should I proceed?
|
|
173
|
+
>
|
|
174
|
+
> 1. ■■□ Probe and bisect
|
|
175
|
+
> 2. ■□□ Show the payload for manual submission:
|
|
176
|
+
> - ➕ the ticket is still created, by hand through the Jira UI
|
|
177
|
+
> 3. ■□□ Skip ticket creation
|
|
178
|
+
|
|
179
|
+
#### 2. If the user picks option 1 (probe and bisect)
|
|
180
|
+
|
|
181
|
+
a. **Probe.** Create a ticket with `<p>ok</p>` as the entire payload. The create call must follow the tagging contract below ([Probe-ticket tagging contract](#probe-ticket-tagging-contract)). If the probe also fails, the problem is call shape, permissions, or the issue itself (not the payload). Stop and report.
|
|
182
|
+
b. **Bisect.** If the probe succeeds, the failure is in the payload's content. Bisect the payload (split in half, test each half, recurse) to isolate the smallest fragment that still triggers `INVALID_INPUT`.
|
|
183
|
+
c. **Cap retries.** Do not exceed 4 retry attempts beyond the original failure. If the bisection has not converged by then, report the smallest failing fragment to the user and stop.
|
|
184
|
+
|
|
185
|
+
#### 3. Record the failure
|
|
186
|
+
|
|
187
|
+
Regardless of which option the user picked, append a single JSON object (one line, without a trailing comma) to `~/ai-artifacts/skill-failures/update-jira-ticket.jsonl`. Create the directory and file if absent.
|
|
188
|
+
|
|
189
|
+
Required fields:
|
|
190
|
+
|
|
191
|
+
```json
|
|
192
|
+
{
|
|
193
|
+
"timestamp": "2026-04-28T03:15:32Z",
|
|
194
|
+
"skill": "update-jira-ticket",
|
|
195
|
+
"project_slug": "codeassembly",
|
|
196
|
+
"failing_fragment": "<example>...</example>",
|
|
197
|
+
"notes": "matched known trigger: <ac:task-list>"
|
|
198
|
+
}
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
- `timestamp`: ISO 8601 UTC.
|
|
202
|
+
- `skill`: Literal string `update-jira-ticket`.
|
|
203
|
+
- `project_slug`: Basename of the repo root (or whatever convention the agent already uses for artefact paths in this session).
|
|
204
|
+
- `failing_fragment`: The smallest payload fragment that reproduced `INVALID_INPUT`. When the user chose option 2 or 3, record the full rejected payload.
|
|
205
|
+
- `notes`: Free-form. Name the suspected trigger class if recognisable, otherwise leave empty.
|
|
206
|
+
|
|
207
|
+
#### Probe-ticket tagging contract
|
|
208
|
+
|
|
209
|
+
When (and only when) a probe ticket is created in step 2a, it **must** have all three markers:
|
|
210
|
+
|
|
211
|
+
- **Label:** Include `mcp-probe` in the `labels` argument of the create call.
|
|
212
|
+
- **Title:** `mcp-probe: {YYYY-MM-DD HH:MM} bisection probe`. Use UTC.
|
|
213
|
+
- **Description:** Prefix the description with `Auto-created by recovery protocol on {YYYY-MM-DD}; safe to delete.` followed by a blank line and then the probe payload.
|
|
214
|
+
|
|
215
|
+
A probe ticket that lacks any of these markers will not be matched by the cleanup query below and may stay in the user's backlog indefinitely.
|
|
216
|
+
|
|
217
|
+
### Probe-ticket cleanup
|
|
218
|
+
|
|
219
|
+
Probe tickets created via the recovery protocol are designed to be swept by a single JQL query:
|
|
220
|
+
|
|
221
|
+
```
|
|
222
|
+
project = <project> AND labels = mcp-probe AND created < -1d
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
Run this query periodically and bulk-transition any matches to a closed/deleted state. Probe tickets created before this skill version went live will not have the `mcp-probe` label and must be cleaned up by hand.
|
|
226
|
+
|
|
227
|
+
### Escalation criterion
|
|
228
|
+
|
|
229
|
+
If recorded failures concentrate in a **new trigger class** that the checker does not currently cover, file a follow-up to add a rule for it. The rule list in `rules.ts` is the canonical inventory of what the checker catches; extending it is the right unit of escalation.
|
|
230
|
+
|
|
231
|
+
If recorded failures are spread across truly **unknown classes** (without a clear pattern), the recovery protocol remains the right tool. See [#467](https://github.com/williamthorsen/codeassembly/issues/467) for the prior decision context and [#468](https://github.com/williamthorsen/codeassembly/issues/468) for the generic-logging follow-up.
|
|
232
|
+
|
|
233
|
+
### Antipatterns
|
|
234
|
+
|
|
235
|
+
- Skipping the pre-flight check before invoking `create_jira_issue` / `update_jira_issue`.
|
|
236
|
+
- Creating a probe ticket without the `mcp-probe` label, the deterministic title, and the description prefix.
|
|
237
|
+
- Hand-authoring HTML containing constructs outside the allowlist.
|
|
238
|
+
- Passing `- [ ]` / `- [x]` brackets into `<li>` text instead of rendering a plain bullet.
|
|
239
|
+
- Combining `<code>` with other inline marks on the same text run.
|
|
240
|
+
- Using named HTML entities other than `&`, `<`, `>` in text content.
|
|
241
|
+
- Passing a file path to `description_html` / `comment_html`.
|
|
242
|
+
- Retrying past the 4-retry cap.
|
|
243
|
+
- Skipping the failure record after a recovery: This removes the evidence needed to extend the checker.
|
|
244
|
+
|
|
245
|
+
<!-- include: ../_partials/option-format.md / -->
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
import { createRequire as __cjsCreateRequire } from 'node:module';
|
|
2
|
+
const require = __cjsCreateRequire(import.meta.url);
|
|
3
|
+
var L=Object.defineProperty;var s=(e,r)=>L(e,"name",{value:r,configurable:!0});import{realpathSync as A}from"node:fs";import l from"node:process";import{fileURLToPath as D}from"node:url";function x(e){return e instanceof Error||Object.prototype.toString.call(e)==="[object Error]"}s(x,"isError");function g(e){try{return x(e)&&typeof e.message=="string"&&e.message!==""?e.message:String(e)}catch{return"[unstringifiable value]"}}s(g,"describeError");async function y(e){let r=[];for await(let t of e){if(!Buffer.isBuffer(t))throw new TypeError("readAll: expected Buffer chunks (stream must be in binary mode)");r.push(t)}return Buffer.concat(r).toString("utf8")}s(y,"readAll");var F=new Set(["br","hr","img","input","meta","link","area","base","col","embed","source"]);function T(e){let r=[],t=e.length,n=0,o=0;for(;n<t;){let i=e[n],a=e[n+1]??"";if(i==="<"&&I(a)){n>o&&r.push({type:"text",value:e.slice(o,n),offset:o});let f=O(e,n);r.push(f.token),n=f.nextIndex,o=n}else n+=1}return o<t&&r.push({type:"text",value:e.slice(o,t),offset:o}),r}s(T,"tokenize");function I(e){return e==="/"||e>="a"&&e<="z"||e>="A"&&e<="Z"}s(I,"isTagStartChar");function O(e,r){let t=e[r+1]==="/",n=r+(t?2:1),o=m(e,n,_),i=e.slice(n,o),a=i.toLowerCase();if(t){let R=h(e,o,">"),b=Math.min(R+1,e.length);return{token:{type:"close-tag",name:a,rawName:i,offset:r,raw:e.slice(r,b)},nextIndex:b}}let{attrs:f,selfClosing:c,end:p}=$(e,o),d=p<e.length?p+1:e.length,N=c||F.has(a);return{token:{type:"open-tag",name:a,rawName:i,attrs:f,selfClosing:N,offset:r,raw:e.slice(r,d)},nextIndex:d}}s(O,"parseTag");function $(e,r){let t=e.length,n=[],o=!1,i=r;for(;i<t;){i=k(e,i);let a=e[i];if(a===void 0||a===">")break;if(a==="/"){o=!0,i+=1;continue}let f=i;if(i=m(e,i,W),i===f){i+=1;continue}let c=e.slice(f,i).toLowerCase(),{value:p,next:d}=M(e,i);n.push({name:c,value:p}),i=d}return{attrs:n,selfClosing:o,end:i}}s($,"parseAttributes");function M(e,r){let t=k(e,r);if(e[t]!=="=")return{value:null,next:t};t=k(e,t+1);let n=e[t];if(n==='"'||n==="'"){let a=t+1,f=h(e,a,n),c=f<e.length?f+1:e.length;return{value:e.slice(a,f),next:c}}let o=t,i=m(e,o,a=>!w(a)&&a!==">"&&a!=="/");return{value:e.slice(o,i),next:i}}s(M,"parseAttributeValue");function m(e,r,t){let n=e.length,o=r;for(;o<n;){let i=e[o];if(i===void 0||!t(i))break;o+=1}return o}s(m,"readWhile");function h(e,r,t){let n=e.length,o=r;for(;o<n&&e[o]!==t;)o+=1;return o}s(h,"readUntilChar");function k(e,r){return m(e,r,w)}s(k,"skipWhitespace");function _(e){return e>="a"&&e<="z"||e>="A"&&e<="Z"||e>="0"&&e<="9"||e===":"||e==="-"}s(_,"isNameChar");function W(e){return e>="a"&&e<="z"||e>="A"&&e<="Z"||e>="0"&&e<="9"||e==="-"||e==="_"||e===":"}s(W,"isAttrNameChar");function w(e){return[" "," ",`
|
|
4
|
+
`,"\r","\f"].includes(e)}s(w,"isWhitespace");function u(e,r){let t=1;for(let n=0;n<r&&n<e.length;n+=1)e[n]===`
|
|
5
|
+
`&&(t+=1);return t}s(u,"lineOf");function E(e,r){let t=[];for(let n of e)if(n.type==="open-tag")r(n,t),n.selfClosing||t.push(n);else if(n.type==="close-tag"){for(let o=t.length-1;o>=0;o-=1)if(t[o]?.name===n.name){t.length=o;break}}}s(E,"walkTokens");var z=new Set(["h1","h2","h3","h4","h5","h6","p","ul","ol","li","strong","em","code","a","blockquote","hr","br","table","thead","tbody","tr","th","td"]),v=new Set(["strong","em","a","strike","u","sub","sup"]),j=new Set(["amp","lt","gt"]);function B(e,r){let t=[];return E(e,(n,o)=>{if(n.name==="code"){let i=o.find(a=>v.has(a.name));i&&t.push({rule:"composition-code-inline-mark",snippet:`${i.raw}...${n.raw}`,line:u(r,i.offset),fix:`Move the <code> outside <${i.name}>, or drop the inline mark.`})}else if(v.has(n.name)){let i=o.find(a=>a.name==="code");i&&t.push({rule:"composition-code-inline-mark",snippet:`${i.raw}...${n.raw}`,line:u(r,i.offset),fix:`Move <${n.name}> outside the <code>, or drop the inline mark.`})}}),t}s(B,"compositionCodeInlineMarkRule");function P(e,r){let t=[],n=/&([a-zA-Z][a-zA-Z0-9]*);/g;for(let o of e)if(o.type==="text")for(let i of o.value.matchAll(n)){let a=i[1];if(a===void 0||j.has(a))continue;let f=o.offset+i.index;t.push({rule:"named-entity",snippet:i[0],line:u(r,f),fix:"Replace with literal Unicode (e.g., \u2014 for —, \u2026 for …, a regular space for )."})}return t}s(P,"namedEntityRule");function U(e,r){let t=[];for(let n of e)n.type==="open-tag"&&(n.name.startsWith("ac:")||n.name.startsWith("ri:"))&&t.push({rule:"confluence-construct",snippet:n.raw,line:u(r,n.offset),fix:`Remove the <${n.rawName}> construct. Confluence storage-format elements do not have a Jira analogue.`});return t}s(U,"confluenceConstructRule");function Z(e,r){let t=[];for(let[n,o]of e.entries())o.type!=="open-tag"||o.name!=="pre"||V(e,n)&&t.push({rule:"pre-multiline",snippet:o.raw,line:u(r,o.offset),fix:"Replace the multi-line <pre> with per-line <p><code>...</code></p>, or a single <p> using <br> separators."});return t}s(Z,"preMultilineRule");function V(e,r){let t=1;for(let n=r+1;n<e.length;n+=1){let o=e[n];if(o===void 0)break;if(o.type==="open-tag"&&o.name==="pre"&&!o.selfClosing)t+=1;else if(o.type==="close-tag"&&o.name==="pre"){if(t-=1,t===0)return!1}else if(o.type==="text"&&o.value.includes(`
|
|
6
|
+
`))return!0}return!1}s(V,"hasNewlineInPre");function q(e,r){let t=[];for(let n of e)n.type==="open-tag"&&(z.has(n.name)||n.name.startsWith("ac:")||n.name.startsWith("ri:")||t.push({rule:"disallowed-element",snippet:n.raw,line:u(r,n.offset),fix:`Remove or replace <${n.rawName}>. The allowlist is documented in update-jira-ticket/SKILL.md.`}));return t}s(q,"disallowedElementRule");var S=[B,P,U,Z,q];function C(e){let r=T(e),t=S.flatMap(n=>n(r,e));return t.length===0?{ok:!0}:{ok:!1,findings:t}}s(C,"check");async function J(){try{let e=await y(l.stdin),r=C(e);l.stdout.write(`${JSON.stringify(r,null,2)}
|
|
7
|
+
`)}catch(e){let r=g(e);l.stderr.write(`update-jira-ticket: ${r}
|
|
8
|
+
`),l.exit(1)}}s(J,"main");K()&&await J();function K(){let e=l.argv[1];if(e===void 0)return!1;try{return A(D(import.meta.url))===A(e)}catch(r){let t=g(r);return l.stderr.write(`update-jira-ticket: warning: could not determine entry point: ${t}
|
|
9
|
+
`),!1}}s(K,"isEntryPoint");
|