netresearch/jira-skill / skills/jira-communication
jira-communication
FlaggedUse when handling Jira issues, sprints, boards, links, fields, worklogs, attachments, or users, or on any Jira intent without a key ("create/find a ticket", "pick a project"). Auto-triggers on Jira URLs and issue keys (PROJ-123). Also use when MCP Atlassian tools fail or are unavailable for Jira Server/DC.
scripts/lib/markup_cli.py
View on GitHub# SPDX-License-Identifier: MIT
# SPDX-FileCopyrightText: Netresearch DTT GmbH
"""The three markup gates every wiki-markup write goes through, as CLI helpers.
``lib/markup.py`` holds the grammar and knows nothing about the terminal;
``lib/preview.py`` asks the instance. This module is the part that talks to the
user: it repairs, it reports, and it decides when to abort. Same split as
``lib/users.py``, where ``check_mentions_cli`` wraps the mention lookup.
It exists because these three lived in ``jira-comment.py`` and therefore ran on
exactly two of the seven surfaces that post wiki markup. The other five - a
worklog comment, the comment of ``jira-transition do`` and of ``jira-transition
path``, and the description of ``jira-create issue`` and ``jira-issue update`` -
render the same markup through the same renderer and mangled it the same way.
Seven is counted from the places that POST a body. Counting the mention gate's
call sites instead gives six and misses ``jira-transition path``, which carried
neither gate.
The order is fixed and matters:
1. ``repair_markup`` escapes what can be escaped. A strikethrough span is not a
judgement call, it is a mechanical defect with a mechanical repair.
2. ``check_markup`` reports what cannot: block tags used inline, unbalanced
tags, and anything the escaper left behind.
3. ``check_rendering`` asks the instance, which is the only way to see what no
source-level model can - an autolinked issue key creates a boundary that
exists only where that key resolves.
"""
import functools
import sys
from dataclasses import dataclass, replace
import click
from lib.markup import escape_strikethrough, lint_comment_references, lint_ticket_language, lint_wiki_markup
from lib.output import error, warning
from lib.preview import preflight_render
class _Unset:
"""Sentinel for "not passed", so an explicit ``None`` stays distinguishable.
``render_issue_key=None`` means "render without issue context" and must not
collapse into "fall back to ``issue_key``".
"""
_UNSET = _Unset()
# What the three gates are called on the command line. Kept here so a caller
# adding them does not invent a fourth spelling.
FORCE_HELP = "Post despite wiki-markup lint findings or a struck-through render preview"
NO_AUTO_ESCAPE_HELP = "Do not escape dashes Jira would render as strikethrough; add --force to actually post the span"
NO_PREFLIGHT_HELP = "Skip the render-preview check against the Jira instance before posting"
@dataclass(frozen=True)
class MarkupGates:
"""What the three flags decided, as one value.
They are never meaningful apart - ``--no-auto-escape`` alone does not post
a deliberate strikethrough, because the lint and the render check each
refuse the surviving span - so they travel as one. The same reason
``guard_wiki_markup`` is a single call rather than three.
"""
force: bool
auto_escape: bool
preflight: bool
def offline(self) -> "MarkupGates":
"""The same decision with the render call dropped, for a ``--dry-run``.
The escape and the lint still run: a preview must show the text a real
write would post. Only the part that talks to the instance goes.
"""
return replace(self, preflight=False)
def markup_options(func):
"""Add the three flags to a command and hand them over as one ``gates``.
A command that writes wiki markup takes ``gates: MarkupGates`` instead of
three booleans it would only ever pass on together. Two of three cannot be
wired by accident, and a command does not grow three parameters per gate -
``jira-issue update`` crossed a 13-parameter limit when they were separate.
"""
@functools.wraps(func)
def wrapper(*args, force, no_auto_escape, no_preflight, **kwargs):
kwargs["gates"] = MarkupGates(force=force, auto_escape=not no_auto_escape, preflight=not no_preflight)
return func(*args, **kwargs)
# functools.wraps copies __dict__, which ALIASES __click_params__ rather
# than copying it - the three options below would be appended to the inner
# function's list too. Harmless while each decorated function backs exactly
# one command, and a silent way to give a second command these flags if one
# ever did not.
wrapper.__click_params__ = list(getattr(func, "__click_params__", []))
# Applied bottom-up, so listing them in reverse keeps --force first in
# --help. Asserted by test_every_surface_offers_the_three_flags.
for option in (
click.option("--no-preflight", is_flag=True, help=NO_PREFLIGHT_HELP),
click.option("--no-auto-escape", is_flag=True, help=NO_AUTO_ESCAPE_HELP),
click.option("--force", is_flag=True, help=FORCE_HELP),
):
wrapper = option(wrapper)
return wrapper
def repair_markup(text: str, auto_escape: bool, *, label: str = "text") -> str:
"""Escape dashes Jira would render as strikethrough, and say what changed.
``\\-`` prints as a plain hyphen, so the posted text reads exactly as
written. Reporting the repair on stderr is deliberate - a silent rewrite of
the user's text would be worse than the bug.
``--no-auto-escape`` turns it off, but not on its own: ``check_markup`` and
``check_rendering`` each refuse the surviving span independently, so a
deliberate strikethrough needs ``--no-auto-escape --force``.
"""
if not auto_escape:
return text
repaired = escape_strikethrough(text)
if repaired == text:
return text
changed = [
(n, after)
for n, (before, after) in enumerate(zip(text.split("\n"), repaired.split("\n"), strict=True), 1)
if before != after
]
warning(
f"auto-escaped {len(changed)} line(s) of the {label} that Jira would have rendered struck "
f"through (\\- prints as a plain hyphen; use --no-auto-escape to keep the markup as written)"
)
for n, after in changed[:5]:
warning(f" line {n}: {after.strip()[:100]!r}")
return repaired
def check_markup(text: str, force: bool, issue_key: str | None = None, *, label: str = "text") -> None:
"""Lint wiki markup, ticket language and comment references; abort on findings unless forced.
The two kinds are labelled and explained separately: a language-only
finding reported as a markup problem, with a suggestion about block tags,
sends the reader looking for the wrong defect.
"""
markup_findings = lint_wiki_markup(text)
language_findings = lint_ticket_language(text, issue_key)
reference_findings = lint_comment_references(text)
if not markup_findings and not language_findings and not reference_findings:
return
if force:
for finding in markup_findings:
warning(f"markup: {finding}")
for finding in language_findings:
warning(f"language: {finding}")
for finding in reference_findings:
warning(f"reference: {finding}")
return
labelled = (
[f"markup: {f}" for f in markup_findings]
+ [f"language: {f}" for f in language_findings]
+ [f"reference: {f}" for f in reference_findings]
)
hints = []
if markup_findings:
hints.append("Block tags are never inline; escape literal mentions as \\{code\\}.")
if language_findings:
hints.append("Re-resolve the language for this ticket; quoted user content stays verbatim.")
if reference_findings:
hints.append("Refer to the other comment by time, permalink, heading or timestamp, not by position.")
hints.append("Re-run with --force to post anyway.")
error(f"Lint found problems in the {label}:\n " + "\n ".join(labelled), suggestion=" ".join(hints))
sys.exit(1)
def check_rendering(
text: str,
force: bool,
issue_key: str | None,
enabled: bool,
env_file: str | None = None,
profile: str | None = None,
*,
label: str = "text",
) -> None:
"""Ask the instance how it will render this text, and refuse a mangled write.
The lexical repair handles what a model of the grammar CAN handle. This
handles what it cannot, and the gap is not academic: Jira substitutes
autolinked issue keys before text effects run, so ``OPS-899-x und zu- und``
comes back with ``x und zu`` struck through on an instance where OPS-899
exists and clean on one where it does not: the opener is positioned
relative to the substituted link, not the source text. A resolved issue's
key drawn in ``<del>`` inside its own link is status styling, and
``preflight_render`` does not report it.
Advisory by construction. An unreachable, slow or absent renderer (the
endpoint is Server/DC only) prints one warning and gets out of the way; it
must never stop somebody writing to Jira.
"""
if not enabled:
return
verdict = preflight_render(text, issue_key=issue_key, env_file=env_file, profile=profile)
if not verdict.available:
warning(f"render preview unavailable ({verdict.reason}) - relying on the local markup lint alone")
return
if not verdict.struck:
return
struck = "; ".join(repr(s[:80]) for s in verdict.struck[:3])
if force:
warning(f"rendering: Jira strikes through {struck}")
return
error(
f"Jira renders part of this {label} struck through: {struck}",
suggestion=(
"The local escape could not fix it - this usually means an autolinked issue key "
"(a dash right after PROJ-123) or another macro creating the boundary. Rephrase, "
"put the token in a {code} block, or re-run with --force to write it anyway."
),
)
sys.exit(1)
def guard_wiki_markup(
text: str,
*,
gates: MarkupGates,
issue_key: str | None = None,
render_issue_key: str | None | _Unset = _UNSET,
env_file: str | None = None,
profile: str | None = None,
label: str = "text",
) -> str:
"""Run all three gates in order and return the text to write.
One call so a caller cannot wire up two of the three and believe it is
covered - which is how the description paths went unguarded while the
comment path had the full treatment.
``render_issue_key`` exists for ``jira-create issue``, where the two gates
need different things. The language lint only reads the project part of a
key, so the project key alone answers it. The render endpoint resolves the
key to an actual issue and answers 404 for a project - measured against
jira.netresearch.de - which would print "render preview unavailable" on
every single create. Passing ``None`` renders without issue context, which
the endpoint accepts: the text is checked, only the autolink substitution
that needs a surrounding issue is not.
An absent or empty body passes straight through: ``--comment`` and
``--description`` are optional on most of these commands, and "nothing to
post" is not a markup problem. Returning it unchanged also keeps None a
None, so the caller's own "did the user supply one?" check still works.
"""
if not text or not text.strip():
return text
text = repair_markup(text, gates.auto_escape, label=label)
check_markup(text, gates.force, issue_key, label=label)
key_for_render = issue_key if render_issue_key is _UNSET else render_issue_key
check_rendering(text, gates.force, key_for_render, gates.preflight, env_file, profile, label=label)
return text
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |