diff --git a/docs/assignment-feedback.md b/docs/assignment-feedback.md index 2c211f4..c70e142 100644 --- a/docs/assignment-feedback.md +++ b/docs/assignment-feedback.md @@ -16,7 +16,7 @@ LE 1.93) and the RichText definition in `basic/conventions.html`: | Preflight | `GET .../dropbox/folders/{folder}/submissions/user/{user}` (EntityDropbox, 1.88+) | Exactly one block for this user (`EntityType` User, integer `EntityId`); at least one submission; a `Feedback` key present (null or an object); `Status` 1 (Submitted) or 2 (Draft) as an integer or digit string, never 3 (Published), 0 or unknown; existing feedback must be a complete DropboxFeedbackOut with `IsGraded` exactly `false`, no `Score` or `GradedSymbol`, and empty rubric assessments, files and links; existing draft text, or an existing feedback object whose comment is null or empty (`{}`), only with `--replace-draft` | | Re-check | Both reads again, after an interactive confirmation | A digest of the record's status and existing feedback must match the first preflight; otherwise nothing is sent | | Save | `POST .../feedback/user/{user}`, one attempt, CSRF header fetched before the preflight | Body `{"Score": null, "Feedback": {"Text": ..., "Html": ...}, "RubricAssessments": [], "IsGraded": false, "GradedSymbol": null}`. The reference marks `Feedback` as RichText. Only HTTP 200, the documented success, counts; the response body is undocumented and ignored | -| Readback 1 | `GET .../feedback/user/{user}` (DropboxFeedbackOut) | The same draft-only checks as the preflight. Every comment part that is present, even an empty string, must match: `Text` equal to the comment (line endings normalized), `Html` equal to what was sent, or markup made only of `

` and `
` whose text is the comment (entities decoded, non-breaking spaces as spaces, outer line breaks ignored). Any other markup is a mismatch, and at least one part must be present | +| Readback 1 | `GET .../feedback/user/{user}` (DropboxFeedbackOut) | The same draft-only checks as the preflight. Every comment part that is present, even an empty string, must match: `Text` equal to the comment (line endings normalized), `Html` equal to what was sent, or the same structure: exactly one `

` with no attributes holding only text and attribute-free `
` line breaks, whose text is the comment. Only harmless reformatting is allowed: whitespace outside the paragraph, one line break next to a `

`, `
` or `

` tag, entity spelling (complete references to printable characters only), tag case and `
`/`
`/`
` (non-breaking spaces count as spaces; line breaks, including leading and trailing ones, must match exactly). Any attribute or junk inside a tag, other element, comment, second paragraph, extra `
`, unknown or incomplete entity, or other raw line break is a mismatch and gives `unknown`. At least one part must be present | | Readback 2 | `GET .../submissions/user/{user}` | Same user block, `Status` 2 (Draft), and its `Feedback` passes the same draft-only and comment checks as readback 1 | `IsGraded: false` is the documented draft state ("If true, the feedback is in @@ -52,7 +52,8 @@ synthetic course, assignment and test learner that you own: that learner is unchanged. 5. If the command reports `"outcome": "unknown"` after a save that worked, record the readback shape (`Text`, `Html`, `Status`), because the check - needs adjusting. The likely causes are D2L rewriting `Text`, keeping + needs adjusting. The likely causes are D2L rewriting `Text`, storing `Html` + with attributes, extra elements or more than one paragraph, keeping `Status` at 1, or answering the POST with a status other than 200. 6. Add a draft with a rubric assessment or an attachment in the UI and confirm the command refuses it. diff --git a/lighthouse_cli/assignment_feedback.py b/lighthouse_cli/assignment_feedback.py index 41f79e6..5116a55 100644 --- a/lighthouse_cli/assignment_feedback.py +++ b/lighthouse_cli/assignment_feedback.py @@ -25,11 +25,12 @@ import hashlib import html +import html.entities import json import os -import re import stat from dataclasses import dataclass +from html.parser import HTMLParser from typing import Any import requests @@ -89,21 +90,159 @@ def _html(text: str) -> str: return "

" + html.escape(text, quote=True).replace("\n", "
") + "

" -_OPEN = re.compile(r"^\s*]*>", re.IGNORECASE) -_CLOSE = re.compile(r"

\s*$", re.IGNORECASE) -_BREAK = re.compile(r"|

\s*]*>", re.IGNORECASE) +# ASCII whitespace after line-ending normalization. +_HTML_SPACE = " \t\n\f" + + +class _RejectedMarkupError(Exception): + """The readback Html is not the structure the command sent.""" + + +def _bare_tag(raw: str, prefix: str, name: str, *, slash: bool = False) -> bool: + """``raw`` is ````/```` with only whitespace (and, for ``
``, one slash) before ``>``.""" + head = prefix + name + if raw[:len(head)].lower() != head or not raw.endswith(">"): + return False + rest = raw[len(head):-1].strip(_HTML_SPACE) + return rest == "" or (slash and rest == "/") + + +class _CommentMarkup(HTMLParser): + """Raw token spans of markup that may be one attribute-free ``

`` holding only ``
``. + + The parser finds the tokens; the raw text of every tag is then checked + exactly, and the text between tags is sliced from the source, so a token + the parser drops or rewrites cannot slip through. Comments, declarations, + processing instructions and any other tag raise :class:`_RejectedMarkupError`. + """ + + def __init__(self, markup: str) -> None: + super().__init__(convert_charrefs=False) + self.markup = markup + self._line_starts = [0] + [index + 1 for index, char in enumerate(markup) if char == "\n"] + self.tags: list[tuple[str, int, int]] = [] # (token, start, end) + + def _add(self, token: str, raw: str) -> None: + line, offset = self.getpos() + start = self._line_starts[line - 1] + offset + end = start + len(raw) + if self.markup[start:end] != raw or (self.tags and start < self.tags[-1][2]): + raise _RejectedMarkupError + self.tags.append((token, start, end)) + + def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None: + raw = self.get_starttag_text() or "" + if attrs or tag not in ("p", "br") or not _bare_tag(raw, "<", tag, slash=tag == "br"): + raise _RejectedMarkupError + self._add(tag, raw) + + def handle_startendtag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None: + if tag != "br": + raise _RejectedMarkupError + self.handle_starttag(tag, attrs) + + def handle_endtag(self, tag: str) -> None: + line, offset = self.getpos() + start = self._line_starts[line - 1] + offset + raw = self.markup[start:self.markup.find(">", start) + 1] + if tag != "p" or not _bare_tag(raw, " None: + raise _RejectedMarkupError + + def handle_decl(self, decl: str) -> None: + raise _RejectedMarkupError + + def handle_pi(self, data: str) -> None: + raise _RejectedMarkupError + + def unknown_decl(self, data: str) -> None: + raise _RejectedMarkupError + + +def _character(reference: str) -> str | None: + """The character a complete ``&...;`` reference renders as, or ``None`` if it is not a plain, valid one.""" + body = reference[1:-1] + if not body.startswith("#"): + return html.entities.html5.get(body + ";") + digits, base = (body[2:], 16) if body[1:2] in ("x", "X") else (body[1:], 10) + allowed = "0123456789abcdefABCDEF" if base == 16 else "0123456789" + if not 0 < len(digits) <= 8 or any(char not in allowed for char in digits): + return None + number = int(digits, base) + if number == 9 or 0x20 <= number < 0x7F or ( + 0xA0 <= number <= 0x10FFFF and not 0xD800 <= number <= 0xDFFF + and not 0xFDD0 <= number <= 0xFDEF and number & 0xFFFE != 0xFFFE + ): + return chr(number) + return None + + +def _decode_text(raw: str) -> str | None: + """Text content of raw paragraph text, or ``None`` for markup or an unclear reference. + + A ``<`` that would open a tag, comment or declaration is refused; a ``<`` + or ``&`` that browsers show as-is stays literal. A reference must be + complete (with ``;``) and name a valid, printable character. + """ + out: list[str] = [] + index = 0 + while index < len(raw): + char, following = raw[index], raw[index + 1:index + 2] + if char == "<" and (following == "" or (following.isascii() and (following.isalpha() or following in "/!?"))): + return None + if char != "&" or not (following == "#" or (following.isascii() and following.isalnum())): + out.append(char) + index += 1 + continue + end = index + 1 + while end < len(raw) and raw[end].isascii() and (raw[end].isalnum() or (raw[end] == "#" and end == index + 1)): + end += 1 + if raw[end:end + 1] != ";": + return None + value = _character(raw[index:end + 1]) + if value is None: + return None + out.append(value) + index = end + 1 + return "".join(out) def _comparable(text: str) -> str: - return text.replace("\xa0", " ").strip("\n") + return text.replace("\xa0", " ") def _html_text(markup: str) -> str | None: - """The text of paragraph/line-break-only markup, or ``None`` if it has any other markup.""" - body = _BREAK.sub("\n", _CLOSE.sub("", _OPEN.sub("", _normalize(markup), count=1), count=1)) - if "<" in body: + """The text of markup shaped exactly like :func:`_html` output, or ``None`` for any other structure. + + Allowed reformatting: whitespace outside the paragraph, one line break + directly after ``

``/``
`` or before ``
``/``

``, entity + spelling, tag case and ``
`` vs ``
``. Any other raw line break is + rejected because it renders as a space, not a line break. Line breaks are + compared exactly, leading and trailing ones included. + """ + markup = _normalize(markup) + parser = _CommentMarkup(markup) + try: + parser.feed(markup) + parser.close() + except Exception: # any parser failure means "not the sent structure" + return None + tokens = [token for token, _, _ in parser.tags] + if len(tokens) < 2 or tokens[0] != "p" or tokens[-1] != "/p" or any(t != "br" for t in tokens[1:-1]): + return None + if markup[:parser.tags[0][1]].strip(_HTML_SPACE) or markup[parser.tags[-1][2]:].strip(_HTML_SPACE): return None - return _comparable(html.unescape(body)) + lines = [] + for (_, _, start), (_, end, _) in zip(parser.tags, parser.tags[1:], strict=False): + segment = markup[start:end].removeprefix("\n").removesuffix("\n") + text = None if "\n" in segment else _decode_text(segment) + if text is None or "\n" in text or "\r" in text: + return None + lines.append(text) + return _comparable("\n".join(lines)) def feedback_payload(text: str) -> dict[str, Any]: diff --git a/tests/test_assignment_feedback.py b/tests/test_assignment_feedback.py index 17eb141..431b6d4 100644 --- a/tests/test_assignment_feedback.py +++ b/tests/test_assignment_feedback.py @@ -31,6 +31,9 @@ FeedbackInputError, FeedbackRefusedError, _check_saved_comment, + _comparable, + _html, + _html_text, _UnexpectedError, check_feedback_target, feedback_payload, @@ -712,9 +715,9 @@ def test_readback_accepts_the_html_part_alone_when_it_matches_what_was_sent(feed @pytest.mark.parametrize("markup", [ "

Synthetic draft note: revisit the second proof.
Line two.

", - "

Synthetic draft note: revisit the second proof.

\n

Line two.

", - '

Synthetic draft note: revisit the second proof.
Line two.

', -], ids=["br", "paragraphs", "attributes-nbsp"]) + "

Synthetic draft note: revisit the second proof.
Line two.

", + "\n

\nSynthetic draft note: revisit the second proof.
\nLine two.\n

\n", +], ids=["br", "case-nbsp", "pretty-printed"]) def test_readback_accepts_html_reformatted_with_the_same_text(feedback_file, markup): fake = FakeLMS(happy_routes(get_feedback=[lambda: response(200, draft_feedback_out(Feedback={"Text": TEXT, "Html": markup}))])) result = invoke(fake, "--file", str(feedback_file), "--yes", "--json") @@ -737,14 +740,117 @@ def test_saved_comment_check_rejects_any_difference(rich, text): @pytest.mark.parametrize("rich,text", [ - ({"Text": "hello\n", "Html": "

hello

"}, "hello\n"), ({"Text": None, "Html": "

a & b
c

"}, "a & b\nc"), ({"Text": "a\u00a0b", "Html": "

a b

"}, "a\u00a0b"), -], ids=["trailing-newline-dropped-in-html", "html-only-escaped", "nbsp"]) +], ids=["html-only-escaped", "nbsp"]) def test_saved_comment_check_accepts_equivalent_parts(rich, text): _check_saved_comment(draft_feedback_out(Feedback=rich), text) +_REJECTED_HTML = { + "p-hidden": ("", "hello"), + "p-style": ('

hello

', "hello"), + "p-class": ('

hello

', "hello"), + "p-id": ("

hello

", "hello"), + "br-attribute": ('

a
b

', "a\nb"), + "span": ("

hello

", "hello"), + "nested-p-in-div": ("

hello

", "hello"), + "extra-image": ('

hello

', "hello"), + "script-inside": ("

hello

", "hello"), + "script-after": ("

hello

", "hello"), + "style-inside": ("

hello

", "hello"), + "comment-inside": ("

hello

", "hello"), + "comment-before": ("

hello

", "hello"), + "unfinished-comment": ("

hello

", "& literal", + "xz", "unicode é中\U0001f600", +]) +def test_html_matcher_accepts_exactly_what_was_sent(text): + assert _html_text(_html(text)) == _comparable(text) + + +def test_attribute_paragraph_with_matching_text_reports_unknown(feedback_file): + hidden = feedback_payload(TEXT)["Feedback"]["Html"].replace("

", "