@self-review/core 1.40.1 → 1.41.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/dist/index.cjs CHANGED
@@ -231,13 +231,13 @@ var import_xmllint_wasm = require("xmllint-wasm");
231
231
  var XSD_SCHEMA = `<?xml version="1.0" encoding="UTF-8"?>
232
232
  <xs:schema
233
233
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
234
- xmlns:sr="urn:self-review:v2"
235
- targetNamespace="urn:self-review:v2"
234
+ xmlns:sr="urn:self-review:v3"
235
+ targetNamespace="urn:self-review:v3"
236
236
  elementFormDefault="qualified"
237
237
  >
238
238
 
239
239
  <!--
240
- self-review XML Schema v2
240
+ self-review XML Schema v3
241
241
  =========================
242
242
  Defines the output format for the self-review application.
243
243
  This schema is designed to be both machine-validated and
@@ -254,11 +254,18 @@ var XSD_SCHEMA = `<?xml version="1.0" encoding="UTF-8"?>
254
254
  - Exactly one pair (old-line-* or new-line-*) should be present
255
255
  for line-level comments. This constraint cannot be expressed in
256
256
  XSD 1.0 and is enforced by the application.
257
+ - A <comment> may carry an ordered list of <reply> children, which
258
+ are turns in a conversation about that comment.
257
259
 
258
260
  Changes from v1:
259
261
  - <comment> gained two optional attributes, severity and confidence,
260
262
  so an automated consumer can threshold on findings instead of
261
263
  applying all of them or none of them. See CommentType.
264
+
265
+ Changes from v2:
266
+ - <comment> gained an optional, unbounded <reply> child, so a finding
267
+ and the responses to it form a single legible thread instead of a
268
+ set of disconnected assertions. See ReplyType.
262
269
  -->
263
270
 
264
271
  <!-- ===== Root element ===== -->
@@ -413,6 +420,15 @@ var XSD_SCHEMA = `<?xml version="1.0" encoding="UTF-8"?>
413
420
  </xs:documentation>
414
421
  </xs:annotation>
415
422
  </xs:element>
423
+ <xs:element name="reply" type="sr:ReplyType" minOccurs="0" maxOccurs="unbounded">
424
+ <xs:annotation>
425
+ <xs:documentation>
426
+ Optional ordered list of replies to this comment. The comment
427
+ itself is the root of the thread; each reply is a later turn in
428
+ the conversation about it.
429
+ </xs:documentation>
430
+ </xs:annotation>
431
+ </xs:element>
416
432
  </xs:sequence>
417
433
  <xs:attribute name="old-line-start" type="xs:positiveInteger" use="optional">
418
434
  <xs:annotation>
@@ -496,6 +512,74 @@ var XSD_SCHEMA = `<?xml version="1.0" encoding="UTF-8"?>
496
512
  </xs:attribute>
497
513
  </xs:complexType>
498
514
 
515
+ <xs:complexType name="ReplyType">
516
+ <xs:annotation>
517
+ <xs:documentation>
518
+ A reply to a review comment. Replies turn a finding into a
519
+ conversation: the comment asserts something, a reply answers it, a
520
+ later reply answers that.
521
+
522
+ Four rules govern replies. Only the first is beyond what XSD 1.0
523
+ can express, and it is enforced by the application and by the
524
+ skills that author these documents. Rules 2 to 4 are enforced by
525
+ the content model below; they are spelled out anyway, because the
526
+ reason for a constraint is what an author needs in order to write
527
+ a good reply, and a validator only ever reports the constraint:
528
+
529
+ 1. Replies are ordered. Document order is conversation order, and
530
+ it is the only ordering signal. There are no timestamps and no
531
+ identifiers: the earlier reply is the earlier turn.
532
+
533
+ 2. Replies are flat. A reply is never nested inside another reply.
534
+ A reply that addresses an earlier reply says so in its body.
535
+
536
+ 3. A reply carries no thresholding metadata. There is no category,
537
+ no severity and no confidence on a reply. Those are properties
538
+ of the finding, and the finding is the root comment, whose
539
+ severity and confidence govern the whole thread.
540
+
541
+ 4. A reply carries no suggestion. A concrete counter-proposal goes
542
+ in the reply body as a fenced code block. Allowing a suggestion
543
+ on both the root and a reply would force every consumer to
544
+ invent its own precedence rule.
545
+
546
+ When a machine consumes a thread, the last human turn is the
547
+ tie-breaker over any earlier machine assertion.
548
+ </xs:documentation>
549
+ </xs:annotation>
550
+ <xs:sequence>
551
+ <xs:element name="body" type="xs:string">
552
+ <xs:annotation>
553
+ <xs:documentation>
554
+ The reply text. May contain markdown formatting, including
555
+ fenced code blocks, which is where a counter-proposal goes
556
+ since replies carry no suggestion element.
557
+ </xs:documentation>
558
+ </xs:annotation>
559
+ </xs:element>
560
+ <xs:element name="attachment" type="sr:AttachmentType" minOccurs="0" maxOccurs="unbounded">
561
+ <xs:annotation>
562
+ <xs:documentation>
563
+ Optional image attachment, identical in form and semantics to
564
+ a comment attachment. The path attribute references an image
565
+ file stored in the .self-review-assets/ directory alongside
566
+ the XML output.
567
+ </xs:documentation>
568
+ </xs:annotation>
569
+ </xs:element>
570
+ </xs:sequence>
571
+ <xs:attribute name="author" type="xs:string" use="optional">
572
+ <xs:annotation>
573
+ <xs:documentation>
574
+ The author of this reply, with the same semantics as
575
+ CommentType/@author. When present, the reply was generated by a
576
+ bot or LLM (e.g., "Claude Opus 5"). When absent, the reply is
577
+ the human reviewer's.
578
+ </xs:documentation>
579
+ </xs:annotation>
580
+ </xs:attribute>
581
+ </xs:complexType>
582
+
499
583
  <xs:complexType name="SuggestionType">
500
584
  <xs:annotation>
501
585
  <xs:documentation>
@@ -674,27 +758,47 @@ function extFromMediaType(mediaType) {
674
758
  };
675
759
  return map[mediaType] || "png";
676
760
  }
761
+ function persistAttachments(attachments, idPrefix, assetDir, onWrite) {
762
+ if (!attachments?.length) return attachments;
763
+ return attachments.map((att, index) => {
764
+ if (!att.data) return att;
765
+ onWrite();
766
+ const ext = extFromMediaType(att.mediaType);
767
+ const fileName = `${idPrefix}-${index}.${ext}`;
768
+ const relativePath = `.self-review-assets/${fileName}`;
769
+ if (!fs.existsSync(assetDir)) {
770
+ fs.mkdirSync(assetDir, { recursive: true });
771
+ }
772
+ fs.writeFileSync(path.join(assetDir, fileName), Buffer.from(att.data));
773
+ return { ...att, fileName: relativePath, data: void 0 };
774
+ });
775
+ }
677
776
  function writeAttachments(state, outputFilePath) {
678
777
  const assetDir = path.join(path.dirname(outputFilePath), ".self-review-assets");
679
778
  let hasAttachments = false;
779
+ const markWritten = () => {
780
+ hasAttachments = true;
781
+ };
680
782
  const updatedFiles = state.files.map((file) => ({
681
783
  ...file,
682
- comments: file.comments.map((comment) => {
683
- if (!comment.attachments?.length) return comment;
684
- const updatedAttachments = comment.attachments.map((att, index) => {
685
- if (!att.data) return att;
686
- hasAttachments = true;
687
- const ext = extFromMediaType(att.mediaType);
688
- const fileName = `${comment.id}-${index}.${ext}`;
689
- const relativePath = `.self-review-assets/${fileName}`;
690
- if (!fs.existsSync(assetDir)) {
691
- fs.mkdirSync(assetDir, { recursive: true });
692
- }
693
- fs.writeFileSync(path.join(assetDir, fileName), Buffer.from(att.data));
694
- return { ...att, fileName: relativePath, data: void 0 };
695
- });
696
- return { ...comment, attachments: updatedAttachments };
697
- })
784
+ // Every comment is walked, including one with no attachments of its own:
785
+ // its replies may carry attachments, and short-circuiting on the comment's
786
+ // own list would drop those blobs without a word.
787
+ comments: file.comments.map((comment) => ({
788
+ ...comment,
789
+ attachments: persistAttachments(comment.attachments, comment.id, assetDir, markWritten),
790
+ ...comment.replies ? {
791
+ replies: comment.replies.map((reply) => ({
792
+ ...reply,
793
+ attachments: persistAttachments(
794
+ reply.attachments,
795
+ `${comment.id}-r-${reply.id}`,
796
+ assetDir,
797
+ markWritten
798
+ )
799
+ }))
800
+ } : {}
801
+ }))
698
802
  }));
699
803
  if (hasAttachments) {
700
804
  console.error(`[main] Wrote attachment files to ${assetDir}`);
@@ -707,7 +811,7 @@ async function serializeReview(state, outputFilePath) {
707
811
  try {
708
812
  const validationResult = await (0, import_xmllint_wasm.validateXML)({
709
813
  xml: [{ fileName: "review.xml", contents: xml }],
710
- schema: [{ fileName: "self-review-v2.xsd", contents: XSD_SCHEMA }]
814
+ schema: [{ fileName: "self-review-v3.xsd", contents: XSD_SCHEMA }]
711
815
  });
712
816
  if (!validationResult.valid) {
713
817
  const errors = validationResult.errors || [];
@@ -743,7 +847,7 @@ function buildXml(state) {
743
847
  lines.push('<?xml version="1.0" encoding="UTF-8"?>');
744
848
  const sourceAttrs = buildSourceAttributes(state);
745
849
  lines.push(
746
- `<review xmlns="urn:self-review:v2" timestamp="${escapeXml(state.timestamp)}"${sourceAttrs}>`
850
+ `<review xmlns="urn:self-review:v3" timestamp="${escapeXml(state.timestamp)}"${sourceAttrs}>`
747
851
  );
748
852
  for (const file of state.files) {
749
853
  lines.push(...buildFileXml(file));
@@ -803,14 +907,28 @@ function buildCommentXml(comment) {
803
907
  );
804
908
  lines.push(" </suggestion>");
805
909
  }
806
- if (comment.attachments?.length) {
807
- for (const att of comment.attachments) {
808
- lines.push(` <attachment path="${escapeXml(att.fileName)}" media-type="${escapeXml(att.mediaType)}" />`);
809
- }
910
+ lines.push(...buildAttachmentXml(comment.attachments, " "));
911
+ for (const reply of comment.replies ?? []) {
912
+ lines.push(...buildReplyXml(reply));
810
913
  }
811
914
  lines.push(" </comment>");
812
915
  return lines;
813
916
  }
917
+ function buildAttachmentXml(attachments, indent) {
918
+ if (!attachments?.length) return [];
919
+ return attachments.map(
920
+ (att) => `${indent}<attachment path="${escapeXml(att.fileName)}" media-type="${escapeXml(att.mediaType)}" />`
921
+ );
922
+ }
923
+ function buildReplyXml(reply) {
924
+ const attrStr = reply.author ? ` author="${escapeXml(reply.author)}"` : "";
925
+ return [
926
+ ` <reply${attrStr}>`,
927
+ ` <body>${escapeXml(reply.body)}</body>`,
928
+ ...buildAttachmentXml(reply.attachments, " "),
929
+ " </reply>"
930
+ ];
931
+ }
814
932
  function escapeXml(str) {
815
933
  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
816
934
  }
@@ -837,7 +955,8 @@ function parseReviewXmlString(xmlContent) {
837
955
  const parser = new import_fast_xml_parser.XMLParser({
838
956
  ignoreAttributes: false,
839
957
  attributeNamePrefix: "@_",
840
- allowBooleanAttributes: true
958
+ allowBooleanAttributes: true,
959
+ trimValues: false
841
960
  });
842
961
  try {
843
962
  const result = parser.parse(xmlContent);
@@ -849,36 +968,31 @@ function parseReviewXmlString(xmlContent) {
849
968
  const source = parseSource(review);
850
969
  const comments = [];
851
970
  const viewedFiles = [];
852
- const files = Array.isArray(review.file) ? review.file : review.file ? [review.file] : [];
971
+ const files = toChildArray(review.file);
853
972
  for (const file of files) {
854
- const filePath = file["@_path"];
855
- if (!filePath) continue;
973
+ const rawPath = file["@_path"];
974
+ if (!rawPath) continue;
975
+ const filePath = String(rawPath);
856
976
  if (parseViewed(file["@_viewed"])) {
857
- viewedFiles.push(String(filePath));
977
+ viewedFiles.push(filePath);
858
978
  }
859
- const fileComments = Array.isArray(file.comment) ? file.comment : file.comment ? [file.comment] : [];
979
+ const fileComments = toChildArray(file.comment);
860
980
  for (const comment of fileComments) {
861
981
  const reviewComment = {
862
982
  id: generateId(),
863
983
  filePath,
864
984
  lineRange: parseLineRange(comment),
865
- body: comment.body || "",
866
- category: comment.category || "",
985
+ body: comment.body !== void 0 ? String(comment.body) : "",
986
+ category: comment.category !== void 0 ? String(comment.category) : "",
867
987
  suggestion: parseSuggestion(comment),
868
988
  author: comment["@_author"] ? String(comment["@_author"]) : void 0,
869
989
  severity: parseEnumAttribute(comment["@_severity"], SEVERITY_VALUES),
870
990
  confidence: parseEnumAttribute(comment["@_confidence"], CONFIDENCE_VALUES)
871
991
  };
872
- const commentAttachments = Array.isArray(comment.attachment) ? comment.attachment : comment.attachment ? [comment.attachment] : [];
873
- if (commentAttachments.length > 0) {
874
- reviewComment.attachments = commentAttachments.map(
875
- (att, i) => ({
876
- id: `${reviewComment.id}-att-${i}`,
877
- fileName: String(att["@_path"] || ""),
878
- mediaType: String(att["@_media-type"] || "image/png")
879
- })
880
- );
881
- }
992
+ const attachments = parseAttachments(comment, reviewComment.id);
993
+ if (attachments) reviewComment.attachments = attachments;
994
+ const replies = parseReplies(comment);
995
+ if (replies) reviewComment.replies = replies;
882
996
  comments.push(reviewComment);
883
997
  }
884
998
  }
@@ -945,6 +1059,35 @@ function parseSuggestion(comment) {
945
1059
  proposedCode: String(suggestion["proposed-code"] || "")
946
1060
  };
947
1061
  }
1062
+ function toChildArray(raw) {
1063
+ if (Array.isArray(raw)) return raw;
1064
+ if (raw === void 0 || raw === null) return [];
1065
+ return [raw];
1066
+ }
1067
+ function parseAttachments(node, idPrefix) {
1068
+ const raw = toChildArray(node.attachment);
1069
+ if (raw.length === 0) return void 0;
1070
+ return raw.map((att, i) => ({
1071
+ id: `${idPrefix}-att-${i}`,
1072
+ fileName: String(att["@_path"] || ""),
1073
+ mediaType: String(att["@_media-type"] || "image/png")
1074
+ }));
1075
+ }
1076
+ function parseReplies(comment) {
1077
+ const raw = toChildArray(comment.reply);
1078
+ if (raw.length === 0) return void 0;
1079
+ return raw.map((node) => {
1080
+ const id = generateId();
1081
+ const reply = {
1082
+ id,
1083
+ body: node.body !== void 0 ? String(node.body) : "",
1084
+ author: node["@_author"] ? String(node["@_author"]) : void 0
1085
+ };
1086
+ const attachments = parseAttachments(node, id);
1087
+ if (attachments) reply.attachments = attachments;
1088
+ return reply;
1089
+ });
1090
+ }
948
1091
  function generateId() {
949
1092
  return `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
950
1093
  }