codeassembly-guidance 0.0.0 → 0.2.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 +1320 -0
- package/CHANGELOG.md +315 -0
- package/LICENSE +7 -0
- package/README.md +195 -1
- package/bin/codeassembly-validate-preferences.js +18 -0
- 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 +70 -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 +6 -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 +59 -0
- package/content/collections/all.md +11 -0
- package/content/collections/atlassian.md +17 -0
- package/content/collections/recommended.md +41 -0
- package/content/collections/triage.md +13 -0
- package/content/collections/williamthorsen.md +26 -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 +38 -0
- package/content/guidance/rulebooks/cli-conventions.md +192 -0
- package/content/guidance/rulebooks/codeassembly-content-specification.md +184 -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 +19 -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 +273 -0
- package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
- package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +60 -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 +51 -0
- package/content/scripts/README.md +44 -0
- package/content/scripts/check-branch-currency.mjs +11 -0
- package/content/scripts/check-prose.mjs +171 -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 +214 -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/scripts/validate-preferences.mjs +146 -0
- package/content/skills/_data/action-items.md +83 -0
- package/content/skills/_data/artifact-conventions.md +1001 -0
- package/content/skills/_data/bitbucket-pr-access.md +89 -0
- package/content/skills/_data/branch-currency.md +36 -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/project-stage.md +32 -0
- package/content/skills/_data/recommendation-gradient.md +92 -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 +180 -0
- package/content/skills/_data/title-templates.md +632 -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/jira-task-list-flattening.md +1 -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 +85 -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/assess-usability/SKILL.md +96 -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 +121 -0
- package/content/skills/create-pr/SKILL.md +150 -0
- package/content/skills/create-ticket/SKILL.md +395 -0
- package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
- package/content/skills/derive-session-context/derive-session-context.mjs +149 -0
- package/content/skills/design-and-plan/SKILL.md +197 -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 +247 -0
- package/content/skills/groom-backlog/groom-backlog.mjs +108 -0
- package/content/skills/implement-plan/SKILL.md +168 -0
- package/content/skills/index-prototypes/SKILL.md +200 -0
- package/content/skills/index-prototypes/index-prototypes.mjs +388 -0
- package/content/skills/kb-add/SKILL.md +157 -0
- package/content/skills/kb-add/kb-add.mjs +216 -0
- package/content/skills/kb-curate/SKILL.md +119 -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 +207 -0
- package/content/skills/kb-retrieve-events/SKILL.md +98 -0
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +207 -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 +137 -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 +178 -0
- package/content/skills/pull-from-backlog/SKILL.md +83 -0
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +209 -0
- package/content/skills/refine-plan/SKILL.md +263 -0
- package/content/skills/refine-prototype/SKILL.md +113 -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 +303 -0
- package/content/skills/review-criteria/SKILL.md +141 -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 +148 -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 +71 -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 +317 -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 +235 -0
- package/content/skills/triage-spike-findings/SKILL.md +113 -0
- package/content/skills/triage-spike-findings/triage-spike-findings.mjs +71 -0
- package/content/skills/typescript-testing-conventions/SKILL.md +178 -0
- package/content/skills/update-jira-ticket/SKILL.md +257 -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 +25 -0
- package/content/subagents/_data/rovo.yaml +41 -0
- package/content/subagents/canary.md +12 -0
- package/content/subagents/disposition-challenger.md +78 -0
- package/content/subagents/entry-drafter.md +191 -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 +132 -0
- package/content/subagents/ticket-assessor.md +142 -0
- package/content/subagents/usability-assessor.md +157 -0
- package/package.json +74 -2
- package/schemas/preferences.v1.json +321 -0
- package/schemas/work-types.v1.json +142 -0
|
@@ -0,0 +1,178 @@
|
|
|
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
|
+
## DOM environment
|
|
107
|
+
|
|
108
|
+
A test that renders into a DOM runs under happy-dom, which starts and runs faster than jsdom. Under Vitest, set `environment: 'happy-dom'` or open the file with the `// @vitest-environment happy-dom` pragma; under Jest, use the `@happy-dom/jest-environment` package. A test that constructs a window directly uses happy-dom's `Window` rather than `JSDOM`.
|
|
109
|
+
|
|
110
|
+
Use jsdom only for a test that depends on a behavior that happy-dom lacks, and name that behavior in a comment at the opt-in, so that a reader can check whether happy-dom has since gained it.
|
|
111
|
+
|
|
112
|
+
```typescript
|
|
113
|
+
// ✅ Good: The opt-in names what happy-dom lacks
|
|
114
|
+
// @vitest-environment jsdom
|
|
115
|
+
// happy-dom lacks <the behavior on which this test depends>.
|
|
116
|
+
|
|
117
|
+
// ❌ Avoid: jsdom by habit
|
|
118
|
+
// @vitest-environment jsdom
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
## External programs
|
|
122
|
+
|
|
123
|
+
The `testing-conventions` skill states the rule: Code calls an external program through an adapter, and its tests pass a fake. In TypeScript, the adapter is a type, the code takes it as a parameter whose default is the real adapter, and the test passes an object literal. Prefer the parameter to module mocking (`vi.mock`), which leaves the dependency out of the signature and lets the code keep calling the program directly.
|
|
124
|
+
|
|
125
|
+
```typescript
|
|
126
|
+
// ✅ Good: The code receives git, and the test supplies its answers
|
|
127
|
+
export interface Git {
|
|
128
|
+
listTrackedFiles(root: string): string[];
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
export const realGit: Git = {
|
|
132
|
+
listTrackedFiles: (root) =>
|
|
133
|
+
execFileSync('git', ['ls-files'], { cwd: root, encoding: 'utf8' }).split('\n').filter(Boolean),
|
|
134
|
+
};
|
|
135
|
+
|
|
136
|
+
export function findSkillFiles(root: string, git: Git = realGit): string[] {
|
|
137
|
+
return git.listTrackedFiles(root).filter((path) => path.endsWith('/SKILL.md'));
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
it('returns only the tracked SKILL.md files', () => {
|
|
141
|
+
const git: Git = { listTrackedFiles: () => ['a/SKILL.md', 'a/notes.md'] };
|
|
142
|
+
expect(findSkillFiles('/repo', git)).toStrictEqual(['a/SKILL.md']);
|
|
143
|
+
});
|
|
144
|
+
|
|
145
|
+
// ❌ Avoid: The test builds a real repository to produce the same input
|
|
146
|
+
it('returns only the tracked SKILL.md files', () => {
|
|
147
|
+
execFileSync('git', ['init'], { cwd: scratch });
|
|
148
|
+
// ...write the files, then `git add` and `git commit`...
|
|
149
|
+
expect(findSkillFiles(scratch)).toStrictEqual(['a/SKILL.md']);
|
|
150
|
+
});
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
Only `realGit` has a test that runs git, and that test checks that `listTrackedFiles` parses the output of `git ls-files`.
|
|
154
|
+
|
|
155
|
+
## Console and stream output
|
|
156
|
+
|
|
157
|
+
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.
|
|
158
|
+
|
|
159
|
+
- **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.
|
|
160
|
+
- **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`.
|
|
161
|
+
|
|
162
|
+
```typescript
|
|
163
|
+
import { listConsoleLines, silenceConsole } from '@williamthorsen/toolbelt.vitest/candidate';
|
|
164
|
+
|
|
165
|
+
it('if a deprecated option is passed, warns once', () => {
|
|
166
|
+
using silent = silenceConsole(['warn']);
|
|
167
|
+
parseOptions({ legacy: true });
|
|
168
|
+
expect(listConsoleLines(silent.warn)).toStrictEqual([expect.stringContaining('deprecated')]);
|
|
169
|
+
});
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
When 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:
|
|
173
|
+
|
|
174
|
+
```typescript
|
|
175
|
+
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
Under Jest, `jest.spyOn` takes the same form.
|
|
@@ -0,0 +1,257 @@
|
|
|
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. Also use to identify the Jira client for reading a ticket, including a client that the machine adds through the `jira-clients` guidance hook.'
|
|
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
|
+
<!-- include: ../_partials/jira-task-list-flattening.md / -->
|
|
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`. Doesn't offer an 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
|
+
When the machine adds a client of its own, a section after this one describes it, with the sites to which it connects and where it ranks among these.
|
|
30
|
+
|
|
31
|
+
<!-- guidance-hook: jira-clients -->
|
|
32
|
+
|
|
33
|
+
## ADF path
|
|
34
|
+
|
|
35
|
+
Use this branch when the client is `acli`.
|
|
36
|
+
|
|
37
|
+
1. **Check `acli`'s active site before the first `acli` call.** `acli` acts on whichever site it is signed in to. Compare that site with the ticket's host, taken from the ticket URL, or from `ticket_base_url` when the ticket URL is not known:
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
node {harness_home_dir}/scripts/manage-jira-ticket.mjs check-site --target {ticket URL or ticket_base_url}
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
The helper prints `{"activeSite": ..., "targetSite": ..., "match": ...}` and exits non-zero unless the two match. On a mismatch, use another client from [Identify your client](#identify-your-client); when none remains, report the wrong site by repeating the helper's stderr line, which names both sites and the `acli jira auth switch` command. Never run that command, because the active site is shared by every session on the machine. A non-zero exit without JSON means that `acli` is unavailable. Skip the check when neither URL is known. `manage-jira-ticket.mjs create` runs the same check itself.
|
|
44
|
+
|
|
45
|
+
2. **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:
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
node {harness_home_dir}/scripts/manage-jira-ticket.mjs convert-body --body-file {absolute Markdown path} --out {absolute ADF path}
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
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.
|
|
52
|
+
|
|
53
|
+
3. **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.
|
|
54
|
+
4. **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.
|
|
55
|
+
5. **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.
|
|
56
|
+
6. **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.
|
|
57
|
+
|
|
58
|
+
## Markdown path
|
|
59
|
+
|
|
60
|
+
Use this branch when the client is a `contentFormat`-based tool (e.g. `createJiraIssue` / `editJiraIssue`).
|
|
61
|
+
|
|
62
|
+
1. **Author Markdown.** Prefer a local Markdown artefact when one exists; otherwise compose in Markdown. Pass it via `contentFormat: "markdown"`.
|
|
63
|
+
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.
|
|
64
|
+
3. **Write checklists as plain bullets**, per [Checklists](#checklists).
|
|
65
|
+
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`.
|
|
66
|
+
|
|
67
|
+
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.
|
|
68
|
+
|
|
69
|
+
## HTML path
|
|
70
|
+
|
|
71
|
+
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.
|
|
72
|
+
|
|
73
|
+
### The correct path for the HTML tool
|
|
74
|
+
|
|
75
|
+
1. **Source content as Markdown.** Prefer a local Markdown artefact when one exists. Otherwise, compose in Markdown first; never author HTML directly.
|
|
76
|
+
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.
|
|
77
|
+
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.
|
|
78
|
+
4. **Pass the HTML inline** to `description_html` or `comment_html`.
|
|
79
|
+
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`.
|
|
80
|
+
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.
|
|
81
|
+
|
|
82
|
+
### Pre-flight checker
|
|
83
|
+
|
|
84
|
+
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.
|
|
85
|
+
|
|
86
|
+
#### Invocation
|
|
87
|
+
|
|
88
|
+
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).
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
cat <<'EOF' | node {harness_home_dir}/skills/update-jira-ticket/update-jira-ticket.mjs
|
|
92
|
+
<p>Your rendered HTML payload here.</p>
|
|
93
|
+
EOF
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
#### Output
|
|
97
|
+
|
|
98
|
+
`ok: true` means the payload passes every rule:
|
|
99
|
+
|
|
100
|
+
```json
|
|
101
|
+
{ "ok": true }
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
`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:
|
|
105
|
+
|
|
106
|
+
```json
|
|
107
|
+
{
|
|
108
|
+
"ok": false,
|
|
109
|
+
"findings": [
|
|
110
|
+
{
|
|
111
|
+
"rule": "composition-code-inline-mark",
|
|
112
|
+
"snippet": "<strong>...<code>",
|
|
113
|
+
"line": 12,
|
|
114
|
+
"fix": "Move the <code> outside <strong>, or drop the inline mark."
|
|
115
|
+
}
|
|
116
|
+
]
|
|
117
|
+
}
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
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.
|
|
121
|
+
|
|
122
|
+
#### Acting on findings
|
|
123
|
+
|
|
124
|
+
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.
|
|
125
|
+
|
|
126
|
+
### Allowed elements
|
|
127
|
+
|
|
128
|
+
Exhaustive list. Nothing else.
|
|
129
|
+
|
|
130
|
+
`h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `p`, `ul`, `ol`, `li`, `strong`, `em`, `code`, `a`, `blockquote`, `hr`, `br`, `table`, `thead`, `tbody`, `tr`, `th`, `td`
|
|
131
|
+
|
|
132
|
+
**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.
|
|
133
|
+
|
|
134
|
+
### Composition rules (reference)
|
|
135
|
+
|
|
136
|
+
The pre-flight checker enforces these; this section explains why they exist.
|
|
137
|
+
|
|
138
|
+
#### `<code>` combined with other inline marks
|
|
139
|
+
|
|
140
|
+
`<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.
|
|
141
|
+
|
|
142
|
+
**Workaround:** Move the `<code>` outside the styling wrapper so that the two apply to different text runs, or drop the styling entirely.
|
|
143
|
+
|
|
144
|
+
```html
|
|
145
|
+
<!-- Wrong -->
|
|
146
|
+
<strong><code>isDevMode</code> parameter</strong>
|
|
147
|
+
|
|
148
|
+
<!-- Right (separate text runs) -->
|
|
149
|
+
<strong>The </strong><code>isDevMode</code><strong> parameter</strong>
|
|
150
|
+
|
|
151
|
+
<!-- Also right (drop the styling) -->
|
|
152
|
+
<code>isDevMode</code> parameter
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
#### Multi-line code samples
|
|
156
|
+
|
|
157
|
+
`<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.
|
|
158
|
+
|
|
159
|
+
**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.
|
|
160
|
+
|
|
161
|
+
### Character handling
|
|
162
|
+
|
|
163
|
+
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.
|
|
164
|
+
|
|
165
|
+
| Don't write | Write instead |
|
|
166
|
+
| ----------- | ------------------------ |
|
|
167
|
+
| `—` | `—` (U+2014) |
|
|
168
|
+
| `–` | `–` (U+2013) |
|
|
169
|
+
| `…` | `…` (U+2026) |
|
|
170
|
+
| ` ` | regular space, or U+00A0 |
|
|
171
|
+
| `©` | `©` (U+00A9) |
|
|
172
|
+
| `’` | `'` (U+2019) |
|
|
173
|
+
|
|
174
|
+
`"` 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.
|
|
175
|
+
|
|
176
|
+
### Recovery protocol (backstop)
|
|
177
|
+
|
|
178
|
+
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.
|
|
179
|
+
|
|
180
|
+
#### 1. Report the failure to the user
|
|
181
|
+
|
|
182
|
+
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):
|
|
183
|
+
|
|
184
|
+
> 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?
|
|
185
|
+
>
|
|
186
|
+
> 1. ■■□ Probe and bisect
|
|
187
|
+
> 2. ■□□ Show the payload for manual submission:
|
|
188
|
+
> - ➕ the ticket is still created, by hand through the Jira UI
|
|
189
|
+
> 3. ■□□ Skip ticket creation
|
|
190
|
+
|
|
191
|
+
#### 2. If the user picks option 1 (probe and bisect)
|
|
192
|
+
|
|
193
|
+
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.
|
|
194
|
+
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`.
|
|
195
|
+
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.
|
|
196
|
+
|
|
197
|
+
#### 3. Record the failure
|
|
198
|
+
|
|
199
|
+
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.
|
|
200
|
+
|
|
201
|
+
Required fields:
|
|
202
|
+
|
|
203
|
+
```json
|
|
204
|
+
{
|
|
205
|
+
"timestamp": "2026-04-28T03:15:32Z",
|
|
206
|
+
"skill": "update-jira-ticket",
|
|
207
|
+
"project_slug": "codeassembly",
|
|
208
|
+
"failing_fragment": "<example>...</example>",
|
|
209
|
+
"notes": "matched known trigger: <ac:task-list>"
|
|
210
|
+
}
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
- `timestamp`: ISO 8601 UTC.
|
|
214
|
+
- `skill`: Literal string `update-jira-ticket`.
|
|
215
|
+
- `project_slug`: Basename of the repo root (or whatever convention the agent already uses for artefact paths in this session).
|
|
216
|
+
- `failing_fragment`: The smallest payload fragment that reproduced `INVALID_INPUT`. When the user chose option 2 or 3, record the full rejected payload.
|
|
217
|
+
- `notes`: Free-form. Name the suspected trigger class if recognisable, otherwise leave empty.
|
|
218
|
+
|
|
219
|
+
#### Probe-ticket tagging contract
|
|
220
|
+
|
|
221
|
+
When (and only when) a probe ticket is created in step 2a, it **must** have all three markers:
|
|
222
|
+
|
|
223
|
+
- **Label:** Include `mcp-probe` in the `labels` argument of the create call.
|
|
224
|
+
- **Title:** `mcp-probe: {YYYY-MM-DD HH:MM} bisection probe`. Use UTC.
|
|
225
|
+
- **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.
|
|
226
|
+
|
|
227
|
+
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.
|
|
228
|
+
|
|
229
|
+
### Probe-ticket cleanup
|
|
230
|
+
|
|
231
|
+
Probe tickets created via the recovery protocol are designed to be swept by a single JQL query:
|
|
232
|
+
|
|
233
|
+
```
|
|
234
|
+
project = <project> AND labels = mcp-probe AND created < -1d
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
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.
|
|
238
|
+
|
|
239
|
+
### Escalation criterion
|
|
240
|
+
|
|
241
|
+
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.
|
|
242
|
+
|
|
243
|
+
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.
|
|
244
|
+
|
|
245
|
+
### Antipatterns
|
|
246
|
+
|
|
247
|
+
- Skipping the pre-flight check before invoking `create_jira_issue` / `update_jira_issue`.
|
|
248
|
+
- Creating a probe ticket without the `mcp-probe` label, the deterministic title, and the description prefix.
|
|
249
|
+
- Hand-authoring HTML containing constructs outside the allowlist.
|
|
250
|
+
- Passing `- [ ]` / `- [x]` brackets into `<li>` text instead of rendering a plain bullet.
|
|
251
|
+
- Combining `<code>` with other inline marks on the same text run.
|
|
252
|
+
- Using named HTML entities other than `&`, `<`, `>` in text content.
|
|
253
|
+
- Passing a file path to `description_html` / `comment_html`.
|
|
254
|
+
- Retrying past the 4-retry cap.
|
|
255
|
+
- Skipping the failure record after a recovery: This removes the evidence needed to extend the checker.
|
|
256
|
+
|
|
257
|
+
<!-- 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 I=Object.defineProperty;var s=(e,r)=>I(e,"name",{value:r,configurable:!0});import m from"node:process";function x(e){return e instanceof Error||Object.prototype.toString.call(e)==="[object Error]"}s(x,"isError");function c(e){try{return x(e)&&typeof e.message=="string"&&e.message!==""?e.message:String(e)}catch{return"[unstringifiable value]"}}s(c,"describeError");import{realpathSync as y}from"node:fs";import T from"node:process";import{fileURLToPath as $}from"node:url";function h(e,r){let t=T.argv[1];if(t===void 0)return!1;try{return y($(e))===y(t)}catch(n){return T.stderr.write(`${r}: warning: could not determine entry point: ${c(n)}
|
|
4
|
+
`),!0}}s(h,"isEntryPoint");async function w(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(w,"readAll");var O=new Set(["br","hr","img","input","meta","link","area","base","col","embed","source"]);function E(e){let r=[],t=e.length,n=0,o=0;for(;n<t;){let i=e[n],a=e[n+1]??"";if(i==="<"&&M(a)){n>o&&r.push({type:"text",value:e.slice(o,n),offset:o});let f=_(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(E,"tokenize");function M(e){return e==="/"||e>="a"&&e<="z"||e>="A"&&e<="Z"}s(M,"isTagStartChar");function _(e,r){let t=e[r+1]==="/",n=r+(t?2:1),o=g(e,n,j),i=e.slice(n,o),a=i.toLowerCase();if(t){let F=v(e,o,">"),b=Math.min(F+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:l,end:p}=W(e,o),d=p<e.length?p+1:e.length,L=l||O.has(a);return{token:{type:"open-tag",name:a,rawName:i,attrs:f,selfClosing:L,offset:r,raw:e.slice(r,d)},nextIndex:d}}s(_,"parseTag");function W(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=g(e,i,P),i===f){i+=1;continue}let l=e.slice(f,i).toLowerCase(),{value:p,next:d}=z(e,i);n.push({name:l,value:p}),i=d}return{attrs:n,selfClosing:o,end:i}}s(W,"parseAttributes");function z(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=v(e,a,n),l=f<e.length?f+1:e.length;return{value:e.slice(a,f),next:l}}let o=t,i=g(e,o,a=>!S(a)&&a!==">"&&a!=="/");return{value:e.slice(o,i),next:i}}s(z,"parseAttributeValue");function g(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(g,"readWhile");function v(e,r,t){let n=e.length,o=r;for(;o<n&&e[o]!==t;)o+=1;return o}s(v,"readUntilChar");function k(e,r){return g(e,r,S)}s(k,"skipWhitespace");function j(e){return e>="a"&&e<="z"||e>="A"&&e<="Z"||e>="0"&&e<="9"||e===":"||e==="-"}s(j,"isNameChar");function P(e){return e>="a"&&e<="z"||e>="A"&&e<="Z"||e>="0"&&e<="9"||e==="-"||e==="_"||e===":"}s(P,"isAttrNameChar");function S(e){return[" "," ",`
|
|
5
|
+
`,"\r","\f"].includes(e)}s(S,"isWhitespace");function u(e,r){let t=1;for(let n=0;n<r&&n<e.length;n+=1)e[n]===`
|
|
6
|
+
`&&(t+=1);return t}s(u,"lineOf");function C(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(C,"walkTokens");var B=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"]),A=new Set(["strong","em","a","strike","u","sub","sup"]),U=new Set(["amp","lt","gt"]);function Z(e,r){let t=[];return C(e,(n,o)=>{if(n.name==="code"){let i=o.find(a=>A.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(A.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(Z,"compositionCodeInlineMarkRule");function V(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||U.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(V,"namedEntityRule");function q(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(q,"confluenceConstructRule");function D(e,r){let t=[];for(let[n,o]of e.entries())o.type!=="open-tag"||o.name!=="pre"||J(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(D,"preMultilineRule");function J(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(`
|
|
7
|
+
`))return!0}return!1}s(J,"hasNewlineInPre");function K(e,r){let t=[];for(let n of e)n.type==="open-tag"&&(B.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(K,"disallowedElementRule");var N=[Z,V,q,D,K];function R(e){let r=E(e),t=N.flatMap(n=>n(r,e));return t.length===0?{ok:!0}:{ok:!1,findings:t}}s(R,"check");async function X(){try{let e=await w(m.stdin),r=R(e);m.stdout.write(`${JSON.stringify(r,null,2)}
|
|
8
|
+
`)}catch(e){let r=c(e);m.stderr.write(`update-jira-ticket: ${r}
|
|
9
|
+
`),m.exit(1)}}s(X,"main");h(import.meta.url,"update-jira-ticket")&&await X();
|