@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.js CHANGED
@@ -165,13 +165,13 @@ import { validateXML } from "xmllint-wasm";
165
165
  var XSD_SCHEMA = `<?xml version="1.0" encoding="UTF-8"?>
166
166
  <xs:schema
167
167
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
168
- xmlns:sr="urn:self-review:v2"
169
- targetNamespace="urn:self-review:v2"
168
+ xmlns:sr="urn:self-review:v3"
169
+ targetNamespace="urn:self-review:v3"
170
170
  elementFormDefault="qualified"
171
171
  >
172
172
 
173
173
  <!--
174
- self-review XML Schema v2
174
+ self-review XML Schema v3
175
175
  =========================
176
176
  Defines the output format for the self-review application.
177
177
  This schema is designed to be both machine-validated and
@@ -188,11 +188,18 @@ var XSD_SCHEMA = `<?xml version="1.0" encoding="UTF-8"?>
188
188
  - Exactly one pair (old-line-* or new-line-*) should be present
189
189
  for line-level comments. This constraint cannot be expressed in
190
190
  XSD 1.0 and is enforced by the application.
191
+ - A <comment> may carry an ordered list of <reply> children, which
192
+ are turns in a conversation about that comment.
191
193
 
192
194
  Changes from v1:
193
195
  - <comment> gained two optional attributes, severity and confidence,
194
196
  so an automated consumer can threshold on findings instead of
195
197
  applying all of them or none of them. See CommentType.
198
+
199
+ Changes from v2:
200
+ - <comment> gained an optional, unbounded <reply> child, so a finding
201
+ and the responses to it form a single legible thread instead of a
202
+ set of disconnected assertions. See ReplyType.
196
203
  -->
197
204
 
198
205
  <!-- ===== Root element ===== -->
@@ -347,6 +354,15 @@ var XSD_SCHEMA = `<?xml version="1.0" encoding="UTF-8"?>
347
354
  </xs:documentation>
348
355
  </xs:annotation>
349
356
  </xs:element>
357
+ <xs:element name="reply" type="sr:ReplyType" minOccurs="0" maxOccurs="unbounded">
358
+ <xs:annotation>
359
+ <xs:documentation>
360
+ Optional ordered list of replies to this comment. The comment
361
+ itself is the root of the thread; each reply is a later turn in
362
+ the conversation about it.
363
+ </xs:documentation>
364
+ </xs:annotation>
365
+ </xs:element>
350
366
  </xs:sequence>
351
367
  <xs:attribute name="old-line-start" type="xs:positiveInteger" use="optional">
352
368
  <xs:annotation>
@@ -430,6 +446,74 @@ var XSD_SCHEMA = `<?xml version="1.0" encoding="UTF-8"?>
430
446
  </xs:attribute>
431
447
  </xs:complexType>
432
448
 
449
+ <xs:complexType name="ReplyType">
450
+ <xs:annotation>
451
+ <xs:documentation>
452
+ A reply to a review comment. Replies turn a finding into a
453
+ conversation: the comment asserts something, a reply answers it, a
454
+ later reply answers that.
455
+
456
+ Four rules govern replies. Only the first is beyond what XSD 1.0
457
+ can express, and it is enforced by the application and by the
458
+ skills that author these documents. Rules 2 to 4 are enforced by
459
+ the content model below; they are spelled out anyway, because the
460
+ reason for a constraint is what an author needs in order to write
461
+ a good reply, and a validator only ever reports the constraint:
462
+
463
+ 1. Replies are ordered. Document order is conversation order, and
464
+ it is the only ordering signal. There are no timestamps and no
465
+ identifiers: the earlier reply is the earlier turn.
466
+
467
+ 2. Replies are flat. A reply is never nested inside another reply.
468
+ A reply that addresses an earlier reply says so in its body.
469
+
470
+ 3. A reply carries no thresholding metadata. There is no category,
471
+ no severity and no confidence on a reply. Those are properties
472
+ of the finding, and the finding is the root comment, whose
473
+ severity and confidence govern the whole thread.
474
+
475
+ 4. A reply carries no suggestion. A concrete counter-proposal goes
476
+ in the reply body as a fenced code block. Allowing a suggestion
477
+ on both the root and a reply would force every consumer to
478
+ invent its own precedence rule.
479
+
480
+ When a machine consumes a thread, the last human turn is the
481
+ tie-breaker over any earlier machine assertion.
482
+ </xs:documentation>
483
+ </xs:annotation>
484
+ <xs:sequence>
485
+ <xs:element name="body" type="xs:string">
486
+ <xs:annotation>
487
+ <xs:documentation>
488
+ The reply text. May contain markdown formatting, including
489
+ fenced code blocks, which is where a counter-proposal goes
490
+ since replies carry no suggestion element.
491
+ </xs:documentation>
492
+ </xs:annotation>
493
+ </xs:element>
494
+ <xs:element name="attachment" type="sr:AttachmentType" minOccurs="0" maxOccurs="unbounded">
495
+ <xs:annotation>
496
+ <xs:documentation>
497
+ Optional image attachment, identical in form and semantics to
498
+ a comment attachment. The path attribute references an image
499
+ file stored in the .self-review-assets/ directory alongside
500
+ the XML output.
501
+ </xs:documentation>
502
+ </xs:annotation>
503
+ </xs:element>
504
+ </xs:sequence>
505
+ <xs:attribute name="author" type="xs:string" use="optional">
506
+ <xs:annotation>
507
+ <xs:documentation>
508
+ The author of this reply, with the same semantics as
509
+ CommentType/@author. When present, the reply was generated by a
510
+ bot or LLM (e.g., "Claude Opus 5"). When absent, the reply is
511
+ the human reviewer's.
512
+ </xs:documentation>
513
+ </xs:annotation>
514
+ </xs:attribute>
515
+ </xs:complexType>
516
+
433
517
  <xs:complexType name="SuggestionType">
434
518
  <xs:annotation>
435
519
  <xs:documentation>
@@ -608,27 +692,47 @@ function extFromMediaType(mediaType) {
608
692
  };
609
693
  return map[mediaType] || "png";
610
694
  }
695
+ function persistAttachments(attachments, idPrefix, assetDir, onWrite) {
696
+ if (!attachments?.length) return attachments;
697
+ return attachments.map((att, index) => {
698
+ if (!att.data) return att;
699
+ onWrite();
700
+ const ext = extFromMediaType(att.mediaType);
701
+ const fileName = `${idPrefix}-${index}.${ext}`;
702
+ const relativePath = `.self-review-assets/${fileName}`;
703
+ if (!fs.existsSync(assetDir)) {
704
+ fs.mkdirSync(assetDir, { recursive: true });
705
+ }
706
+ fs.writeFileSync(path.join(assetDir, fileName), Buffer.from(att.data));
707
+ return { ...att, fileName: relativePath, data: void 0 };
708
+ });
709
+ }
611
710
  function writeAttachments(state, outputFilePath) {
612
711
  const assetDir = path.join(path.dirname(outputFilePath), ".self-review-assets");
613
712
  let hasAttachments = false;
713
+ const markWritten = () => {
714
+ hasAttachments = true;
715
+ };
614
716
  const updatedFiles = state.files.map((file) => ({
615
717
  ...file,
616
- comments: file.comments.map((comment) => {
617
- if (!comment.attachments?.length) return comment;
618
- const updatedAttachments = comment.attachments.map((att, index) => {
619
- if (!att.data) return att;
620
- hasAttachments = true;
621
- const ext = extFromMediaType(att.mediaType);
622
- const fileName = `${comment.id}-${index}.${ext}`;
623
- const relativePath = `.self-review-assets/${fileName}`;
624
- if (!fs.existsSync(assetDir)) {
625
- fs.mkdirSync(assetDir, { recursive: true });
626
- }
627
- fs.writeFileSync(path.join(assetDir, fileName), Buffer.from(att.data));
628
- return { ...att, fileName: relativePath, data: void 0 };
629
- });
630
- return { ...comment, attachments: updatedAttachments };
631
- })
718
+ // Every comment is walked, including one with no attachments of its own:
719
+ // its replies may carry attachments, and short-circuiting on the comment's
720
+ // own list would drop those blobs without a word.
721
+ comments: file.comments.map((comment) => ({
722
+ ...comment,
723
+ attachments: persistAttachments(comment.attachments, comment.id, assetDir, markWritten),
724
+ ...comment.replies ? {
725
+ replies: comment.replies.map((reply) => ({
726
+ ...reply,
727
+ attachments: persistAttachments(
728
+ reply.attachments,
729
+ `${comment.id}-r-${reply.id}`,
730
+ assetDir,
731
+ markWritten
732
+ )
733
+ }))
734
+ } : {}
735
+ }))
632
736
  }));
633
737
  if (hasAttachments) {
634
738
  console.error(`[main] Wrote attachment files to ${assetDir}`);
@@ -641,7 +745,7 @@ async function serializeReview(state, outputFilePath) {
641
745
  try {
642
746
  const validationResult = await validateXML({
643
747
  xml: [{ fileName: "review.xml", contents: xml }],
644
- schema: [{ fileName: "self-review-v2.xsd", contents: XSD_SCHEMA }]
748
+ schema: [{ fileName: "self-review-v3.xsd", contents: XSD_SCHEMA }]
645
749
  });
646
750
  if (!validationResult.valid) {
647
751
  const errors = validationResult.errors || [];
@@ -677,7 +781,7 @@ function buildXml(state) {
677
781
  lines.push('<?xml version="1.0" encoding="UTF-8"?>');
678
782
  const sourceAttrs = buildSourceAttributes(state);
679
783
  lines.push(
680
- `<review xmlns="urn:self-review:v2" timestamp="${escapeXml(state.timestamp)}"${sourceAttrs}>`
784
+ `<review xmlns="urn:self-review:v3" timestamp="${escapeXml(state.timestamp)}"${sourceAttrs}>`
681
785
  );
682
786
  for (const file of state.files) {
683
787
  lines.push(...buildFileXml(file));
@@ -737,14 +841,28 @@ function buildCommentXml(comment) {
737
841
  );
738
842
  lines.push(" </suggestion>");
739
843
  }
740
- if (comment.attachments?.length) {
741
- for (const att of comment.attachments) {
742
- lines.push(` <attachment path="${escapeXml(att.fileName)}" media-type="${escapeXml(att.mediaType)}" />`);
743
- }
844
+ lines.push(...buildAttachmentXml(comment.attachments, " "));
845
+ for (const reply of comment.replies ?? []) {
846
+ lines.push(...buildReplyXml(reply));
744
847
  }
745
848
  lines.push(" </comment>");
746
849
  return lines;
747
850
  }
851
+ function buildAttachmentXml(attachments, indent) {
852
+ if (!attachments?.length) return [];
853
+ return attachments.map(
854
+ (att) => `${indent}<attachment path="${escapeXml(att.fileName)}" media-type="${escapeXml(att.mediaType)}" />`
855
+ );
856
+ }
857
+ function buildReplyXml(reply) {
858
+ const attrStr = reply.author ? ` author="${escapeXml(reply.author)}"` : "";
859
+ return [
860
+ ` <reply${attrStr}>`,
861
+ ` <body>${escapeXml(reply.body)}</body>`,
862
+ ...buildAttachmentXml(reply.attachments, " "),
863
+ " </reply>"
864
+ ];
865
+ }
748
866
  function escapeXml(str) {
749
867
  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
750
868
  }
@@ -771,7 +889,8 @@ function parseReviewXmlString(xmlContent) {
771
889
  const parser = new XMLParser({
772
890
  ignoreAttributes: false,
773
891
  attributeNamePrefix: "@_",
774
- allowBooleanAttributes: true
892
+ allowBooleanAttributes: true,
893
+ trimValues: false
775
894
  });
776
895
  try {
777
896
  const result = parser.parse(xmlContent);
@@ -783,36 +902,31 @@ function parseReviewXmlString(xmlContent) {
783
902
  const source = parseSource(review);
784
903
  const comments = [];
785
904
  const viewedFiles = [];
786
- const files = Array.isArray(review.file) ? review.file : review.file ? [review.file] : [];
905
+ const files = toChildArray(review.file);
787
906
  for (const file of files) {
788
- const filePath = file["@_path"];
789
- if (!filePath) continue;
907
+ const rawPath = file["@_path"];
908
+ if (!rawPath) continue;
909
+ const filePath = String(rawPath);
790
910
  if (parseViewed(file["@_viewed"])) {
791
- viewedFiles.push(String(filePath));
911
+ viewedFiles.push(filePath);
792
912
  }
793
- const fileComments = Array.isArray(file.comment) ? file.comment : file.comment ? [file.comment] : [];
913
+ const fileComments = toChildArray(file.comment);
794
914
  for (const comment of fileComments) {
795
915
  const reviewComment = {
796
916
  id: generateId(),
797
917
  filePath,
798
918
  lineRange: parseLineRange(comment),
799
- body: comment.body || "",
800
- category: comment.category || "",
919
+ body: comment.body !== void 0 ? String(comment.body) : "",
920
+ category: comment.category !== void 0 ? String(comment.category) : "",
801
921
  suggestion: parseSuggestion(comment),
802
922
  author: comment["@_author"] ? String(comment["@_author"]) : void 0,
803
923
  severity: parseEnumAttribute(comment["@_severity"], SEVERITY_VALUES),
804
924
  confidence: parseEnumAttribute(comment["@_confidence"], CONFIDENCE_VALUES)
805
925
  };
806
- const commentAttachments = Array.isArray(comment.attachment) ? comment.attachment : comment.attachment ? [comment.attachment] : [];
807
- if (commentAttachments.length > 0) {
808
- reviewComment.attachments = commentAttachments.map(
809
- (att, i) => ({
810
- id: `${reviewComment.id}-att-${i}`,
811
- fileName: String(att["@_path"] || ""),
812
- mediaType: String(att["@_media-type"] || "image/png")
813
- })
814
- );
815
- }
926
+ const attachments = parseAttachments(comment, reviewComment.id);
927
+ if (attachments) reviewComment.attachments = attachments;
928
+ const replies = parseReplies(comment);
929
+ if (replies) reviewComment.replies = replies;
816
930
  comments.push(reviewComment);
817
931
  }
818
932
  }
@@ -879,6 +993,35 @@ function parseSuggestion(comment) {
879
993
  proposedCode: String(suggestion["proposed-code"] || "")
880
994
  };
881
995
  }
996
+ function toChildArray(raw) {
997
+ if (Array.isArray(raw)) return raw;
998
+ if (raw === void 0 || raw === null) return [];
999
+ return [raw];
1000
+ }
1001
+ function parseAttachments(node, idPrefix) {
1002
+ const raw = toChildArray(node.attachment);
1003
+ if (raw.length === 0) return void 0;
1004
+ return raw.map((att, i) => ({
1005
+ id: `${idPrefix}-att-${i}`,
1006
+ fileName: String(att["@_path"] || ""),
1007
+ mediaType: String(att["@_media-type"] || "image/png")
1008
+ }));
1009
+ }
1010
+ function parseReplies(comment) {
1011
+ const raw = toChildArray(comment.reply);
1012
+ if (raw.length === 0) return void 0;
1013
+ return raw.map((node) => {
1014
+ const id = generateId();
1015
+ const reply = {
1016
+ id,
1017
+ body: node.body !== void 0 ? String(node.body) : "",
1018
+ author: node["@_author"] ? String(node["@_author"]) : void 0
1019
+ };
1020
+ const attachments = parseAttachments(node, id);
1021
+ if (attachments) reply.attachments = attachments;
1022
+ return reply;
1023
+ });
1024
+ }
882
1025
  function generateId() {
883
1026
  return `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
884
1027
  }