@self-review/core 1.38.0 → 1.39.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
@@ -227,11 +227,38 @@ var import_xmllint_wasm = require("xmllint-wasm");
227
227
  var XSD_SCHEMA = `<?xml version="1.0" encoding="UTF-8"?>
228
228
  <xs:schema
229
229
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
230
- xmlns:sr="urn:self-review:v1"
231
- targetNamespace="urn:self-review:v1"
230
+ xmlns:sr="urn:self-review:v2"
231
+ targetNamespace="urn:self-review:v2"
232
232
  elementFormDefault="qualified"
233
233
  >
234
234
 
235
+ <!--
236
+ self-review XML Schema v2
237
+ =========================
238
+ Defines the output format for the self-review application.
239
+ This schema is designed to be both machine-validated and
240
+ fed to an LLM so it can understand the structure of review feedback.
241
+
242
+ Key concepts:
243
+ - A <review> contains one <file> per file in the diff.
244
+ - A <file> contains zero or more <comment> elements.
245
+ - A <comment> with no line attributes is a file-level comment.
246
+ - A <comment> with old-line-start/old-line-end refers to lines
247
+ in the pre-change version of the file (typically deleted lines).
248
+ - A <comment> with new-line-start/new-line-end refers to lines
249
+ in the post-change version of the file (added or context lines).
250
+ - Exactly one pair (old-line-* or new-line-*) should be present
251
+ for line-level comments. This constraint cannot be expressed in
252
+ XSD 1.0 and is enforced by the application.
253
+
254
+ Changes from v1:
255
+ - <comment> gained two optional attributes, severity and confidence,
256
+ so an automated consumer can threshold on findings instead of
257
+ applying all of them or none of them. See CommentType.
258
+ -->
259
+
260
+ <!-- ===== Root element ===== -->
261
+
235
262
  <xs:element name="review" type="sr:ReviewType">
236
263
  <xs:annotation>
237
264
  <xs:documentation>
@@ -241,6 +268,8 @@ var XSD_SCHEMA = `<?xml version="1.0" encoding="UTF-8"?>
241
268
  </xs:annotation>
242
269
  </xs:element>
243
270
 
271
+ <!-- ===== Complex types ===== -->
272
+
244
273
  <xs:complexType name="ReviewType">
245
274
  <xs:sequence>
246
275
  <xs:element name="file" type="sr:FileType" minOccurs="0" maxOccurs="unbounded" />
@@ -336,6 +365,12 @@ var XSD_SCHEMA = `<?xml version="1.0" encoding="UTF-8"?>
336
365
  For single-line comments, start and end are equal.
337
366
  Exactly one pair (old or new) should be present for line-level
338
367
  comments. Both pairs absent = file-level comment.
368
+
369
+ The category child says what kind of finding this is. The severity
370
+ and confidence attributes say how much weight to put on it: severity
371
+ is how consequential the finding is if it is real, confidence is how
372
+ sure the author is that it is real. They are independent, and an
373
+ automated consumer is expected to threshold on both.
339
374
  </xs:documentation>
340
375
  </xs:annotation>
341
376
  <xs:sequence>
@@ -417,6 +452,44 @@ var XSD_SCHEMA = `<?xml version="1.0" encoding="UTF-8"?>
417
452
  </xs:documentation>
418
453
  </xs:annotation>
419
454
  </xs:attribute>
455
+ <xs:attribute name="severity" type="sr:SeverityEnum" use="optional">
456
+ <xs:annotation>
457
+ <xs:documentation>
458
+ How consequential this finding is if it turns out to be real.
459
+ Judge the impact of the problem, not how confident you are that
460
+ the problem exists, and not how much work the fix is.
461
+
462
+ This attribute has no schema default on purpose. When it is
463
+ absent, a consumer must treat the comment as falling below any
464
+ severity floor it applies, i.e. absent never satisfies a
465
+ threshold. Comments written by a human in the self-review UI
466
+ normally carry no severity.
467
+ </xs:documentation>
468
+ </xs:annotation>
469
+ </xs:attribute>
470
+ <xs:attribute name="confidence" type="sr:ConfidenceEnum" use="optional">
471
+ <xs:annotation>
472
+ <xs:documentation>
473
+ How sure the author is that this finding is real, i.e. that it
474
+ describes an actual defect in the code as written rather than a
475
+ hypothetical one.
476
+
477
+ Confidence is about the evidence, not about how strongly the
478
+ comment is worded. A finding whose argument depends on a
479
+ constraint that is not visible in the diff, on a caller that was
480
+ not read, or on a failure scenario that was imagined rather than
481
+ traced, is low confidence however plausible its prose sounds.
482
+ LLM reviewers systematically overstate certainty here; a
483
+ consumer thresholding on this attribute is relying on it being
484
+ lowered honestly.
485
+
486
+ This attribute has no schema default on purpose. When it is
487
+ absent, a consumer must treat the comment as falling below any
488
+ confidence floor it applies, i.e. absent never satisfies a
489
+ threshold.
490
+ </xs:documentation>
491
+ </xs:annotation>
492
+ </xs:attribute>
420
493
  </xs:complexType>
421
494
 
422
495
  <xs:complexType name="SuggestionType">
@@ -468,6 +541,8 @@ var XSD_SCHEMA = `<?xml version="1.0" encoding="UTF-8"?>
468
541
  </xs:attribute>
469
542
  </xs:complexType>
470
543
 
544
+ <!-- ===== Simple types ===== -->
545
+
471
546
  <xs:simpleType name="ChangeTypeEnum">
472
547
  <xs:annotation>
473
548
  <xs:documentation>
@@ -498,6 +573,93 @@ var XSD_SCHEMA = `<?xml version="1.0" encoding="UTF-8"?>
498
573
  </xs:restriction>
499
574
  </xs:simpleType>
500
575
 
576
+ <xs:simpleType name="SeverityEnum">
577
+ <xs:annotation>
578
+ <xs:documentation>
579
+ How consequential a finding is if it is real. Ordered from most to
580
+ least consequential: critical, major, minor, info.
581
+ </xs:documentation>
582
+ </xs:annotation>
583
+ <xs:restriction base="xs:string">
584
+ <xs:enumeration value="critical">
585
+ <xs:annotation>
586
+ <xs:documentation>
587
+ Causes data loss, a security hole, or a crash or corruption on a
588
+ path that real usage reaches. Shipping this is not acceptable.
589
+ </xs:documentation>
590
+ </xs:annotation>
591
+ </xs:enumeration>
592
+ <xs:enumeration value="major">
593
+ <xs:annotation>
594
+ <xs:documentation>
595
+ Produces wrong behaviour, or breaks a documented contract, on a
596
+ path that real usage reaches. The code does not do what it is
597
+ supposed to do, but nothing is destroyed and there is no security
598
+ impact.
599
+ </xs:documentation>
600
+ </xs:annotation>
601
+ </xs:enumeration>
602
+ <xs:enumeration value="minor">
603
+ <xs:annotation>
604
+ <xs:documentation>
605
+ Real but bounded: a mishandled edge case that is unlikely to be
606
+ hit, a missing test, a leak of something cheap, or a maintenance
607
+ hazard that will cost time later. Behaviour is correct today.
608
+ </xs:documentation>
609
+ </xs:annotation>
610
+ </xs:enumeration>
611
+ <xs:enumeration value="info">
612
+ <xs:annotation>
613
+ <xs:documentation>
614
+ No defect. Style, naming, phrasing, a question for the author, or
615
+ a note recorded for context. Nothing is wrong if this is never
616
+ acted on.
617
+ </xs:documentation>
618
+ </xs:annotation>
619
+ </xs:enumeration>
620
+ </xs:restriction>
621
+ </xs:simpleType>
622
+
623
+ <xs:simpleType name="ConfidenceEnum">
624
+ <xs:annotation>
625
+ <xs:documentation>
626
+ How sure the author is that a finding is real. Ordered from most to
627
+ least sure: high, medium, low.
628
+ </xs:documentation>
629
+ </xs:annotation>
630
+ <xs:restriction base="xs:string">
631
+ <xs:enumeration value="high">
632
+ <xs:annotation>
633
+ <xs:documentation>
634
+ The evidence is in the code that was read. The failure can be
635
+ traced from the diff itself, and no assumption about unseen code,
636
+ unseen callers, or unstated requirements is needed to reach it.
637
+ </xs:documentation>
638
+ </xs:annotation>
639
+ </xs:enumeration>
640
+ <xs:enumeration value="medium">
641
+ <xs:annotation>
642
+ <xs:documentation>
643
+ Likely real, but it rests on one assumption that was not verified,
644
+ such as how a caller behaves, what a dependency guarantees, or
645
+ what the intended requirement was. Stating that assumption in the
646
+ body is expected at this level.
647
+ </xs:documentation>
648
+ </xs:annotation>
649
+ </xs:enumeration>
650
+ <xs:enumeration value="low">
651
+ <xs:annotation>
652
+ <xs:documentation>
653
+ Speculative. The failure scenario was imagined rather than traced,
654
+ or the finding depends on a constraint the author invented, or the
655
+ author could not tell intent from the code. Worth a human's eyes,
656
+ not worth acting on unattended.
657
+ </xs:documentation>
658
+ </xs:annotation>
659
+ </xs:enumeration>
660
+ </xs:restriction>
661
+ </xs:simpleType>
662
+
501
663
  </xs:schema>`;
502
664
  function extFromMediaType(mediaType) {
503
665
  const map = {
@@ -541,7 +703,7 @@ async function serializeReview(state, outputFilePath) {
541
703
  try {
542
704
  const validationResult = await (0, import_xmllint_wasm.validateXML)({
543
705
  xml: [{ fileName: "review.xml", contents: xml }],
544
- schema: [{ fileName: "self-review-v1.xsd", contents: XSD_SCHEMA }]
706
+ schema: [{ fileName: "self-review-v2.xsd", contents: XSD_SCHEMA }]
545
707
  });
546
708
  if (!validationResult.valid) {
547
709
  const errors = validationResult.errors || [];
@@ -577,7 +739,7 @@ function buildXml(state) {
577
739
  lines.push('<?xml version="1.0" encoding="UTF-8"?>');
578
740
  const sourceAttrs = buildSourceAttributes(state);
579
741
  lines.push(
580
- `<review xmlns="urn:self-review:v1" timestamp="${escapeXml(state.timestamp)}"${sourceAttrs}>`
742
+ `<review xmlns="urn:self-review:v2" timestamp="${escapeXml(state.timestamp)}"${sourceAttrs}>`
581
743
  );
582
744
  for (const file of state.files) {
583
745
  lines.push(...buildFileXml(file));
@@ -617,6 +779,12 @@ function buildCommentXml(comment) {
617
779
  if (comment.author) {
618
780
  attrs.push(`author="${escapeXml(comment.author)}"`);
619
781
  }
782
+ if (comment.severity) {
783
+ attrs.push(`severity="${comment.severity}"`);
784
+ }
785
+ if (comment.confidence) {
786
+ attrs.push(`confidence="${comment.confidence}"`);
787
+ }
620
788
  const attrStr = attrs.length > 0 ? " " + attrs.join(" ") : "";
621
789
  lines.push(` <comment${attrStr}>`);
622
790
  lines.push(` <body>${escapeXml(comment.body)}</body>`);
@@ -646,6 +814,8 @@ function escapeXml(str) {
646
814
  // src/xml-parser.ts
647
815
  var import_fs = require("fs");
648
816
  var import_fast_xml_parser = require("fast-xml-parser");
817
+ var SEVERITY_VALUES = ["critical", "major", "minor", "info"];
818
+ var CONFIDENCE_VALUES = ["high", "medium", "low"];
649
819
  function parseReviewXml(xmlPath) {
650
820
  try {
651
821
  const xmlContent = (0, import_fs.readFileSync)(xmlPath, "utf-8");
@@ -687,7 +857,9 @@ function parseReviewXmlString(xmlContent) {
687
857
  body: comment.body || "",
688
858
  category: comment.category || "",
689
859
  suggestion: parseSuggestion(comment),
690
- author: comment["@_author"] ? String(comment["@_author"]) : void 0
860
+ author: comment["@_author"] ? String(comment["@_author"]) : void 0,
861
+ severity: parseEnumAttribute(comment["@_severity"], SEVERITY_VALUES),
862
+ confidence: parseEnumAttribute(comment["@_confidence"], CONFIDENCE_VALUES)
691
863
  };
692
864
  const commentAttachments = Array.isArray(comment.attachment) ? comment.attachment : comment.attachment ? [comment.attachment] : [];
693
865
  if (commentAttachments.length > 0) {
@@ -712,6 +884,11 @@ function parseReviewXmlString(xmlContent) {
712
884
  process.exit(1);
713
885
  }
714
886
  }
887
+ function parseEnumAttribute(raw, allowed) {
888
+ if (raw === void 0 || raw === null) return void 0;
889
+ const value = String(raw);
890
+ return allowed.includes(value) ? value : void 0;
891
+ }
715
892
  function parseSource(review) {
716
893
  const sourcePath = review["@_source-path"];
717
894
  if (sourcePath) {