@self-review/core 1.37.1 → 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.js CHANGED
@@ -165,11 +165,38 @@ 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:v1"
169
- targetNamespace="urn:self-review:v1"
168
+ xmlns:sr="urn:self-review:v2"
169
+ targetNamespace="urn:self-review:v2"
170
170
  elementFormDefault="qualified"
171
171
  >
172
172
 
173
+ <!--
174
+ self-review XML Schema v2
175
+ =========================
176
+ Defines the output format for the self-review application.
177
+ This schema is designed to be both machine-validated and
178
+ fed to an LLM so it can understand the structure of review feedback.
179
+
180
+ Key concepts:
181
+ - A <review> contains one <file> per file in the diff.
182
+ - A <file> contains zero or more <comment> elements.
183
+ - A <comment> with no line attributes is a file-level comment.
184
+ - A <comment> with old-line-start/old-line-end refers to lines
185
+ in the pre-change version of the file (typically deleted lines).
186
+ - A <comment> with new-line-start/new-line-end refers to lines
187
+ in the post-change version of the file (added or context lines).
188
+ - Exactly one pair (old-line-* or new-line-*) should be present
189
+ for line-level comments. This constraint cannot be expressed in
190
+ XSD 1.0 and is enforced by the application.
191
+
192
+ Changes from v1:
193
+ - <comment> gained two optional attributes, severity and confidence,
194
+ so an automated consumer can threshold on findings instead of
195
+ applying all of them or none of them. See CommentType.
196
+ -->
197
+
198
+ <!-- ===== Root element ===== -->
199
+
173
200
  <xs:element name="review" type="sr:ReviewType">
174
201
  <xs:annotation>
175
202
  <xs:documentation>
@@ -179,6 +206,8 @@ var XSD_SCHEMA = `<?xml version="1.0" encoding="UTF-8"?>
179
206
  </xs:annotation>
180
207
  </xs:element>
181
208
 
209
+ <!-- ===== Complex types ===== -->
210
+
182
211
  <xs:complexType name="ReviewType">
183
212
  <xs:sequence>
184
213
  <xs:element name="file" type="sr:FileType" minOccurs="0" maxOccurs="unbounded" />
@@ -274,6 +303,12 @@ var XSD_SCHEMA = `<?xml version="1.0" encoding="UTF-8"?>
274
303
  For single-line comments, start and end are equal.
275
304
  Exactly one pair (old or new) should be present for line-level
276
305
  comments. Both pairs absent = file-level comment.
306
+
307
+ The category child says what kind of finding this is. The severity
308
+ and confidence attributes say how much weight to put on it: severity
309
+ is how consequential the finding is if it is real, confidence is how
310
+ sure the author is that it is real. They are independent, and an
311
+ automated consumer is expected to threshold on both.
277
312
  </xs:documentation>
278
313
  </xs:annotation>
279
314
  <xs:sequence>
@@ -355,6 +390,44 @@ var XSD_SCHEMA = `<?xml version="1.0" encoding="UTF-8"?>
355
390
  </xs:documentation>
356
391
  </xs:annotation>
357
392
  </xs:attribute>
393
+ <xs:attribute name="severity" type="sr:SeverityEnum" use="optional">
394
+ <xs:annotation>
395
+ <xs:documentation>
396
+ How consequential this finding is if it turns out to be real.
397
+ Judge the impact of the problem, not how confident you are that
398
+ the problem exists, and not how much work the fix is.
399
+
400
+ This attribute has no schema default on purpose. When it is
401
+ absent, a consumer must treat the comment as falling below any
402
+ severity floor it applies, i.e. absent never satisfies a
403
+ threshold. Comments written by a human in the self-review UI
404
+ normally carry no severity.
405
+ </xs:documentation>
406
+ </xs:annotation>
407
+ </xs:attribute>
408
+ <xs:attribute name="confidence" type="sr:ConfidenceEnum" use="optional">
409
+ <xs:annotation>
410
+ <xs:documentation>
411
+ How sure the author is that this finding is real, i.e. that it
412
+ describes an actual defect in the code as written rather than a
413
+ hypothetical one.
414
+
415
+ Confidence is about the evidence, not about how strongly the
416
+ comment is worded. A finding whose argument depends on a
417
+ constraint that is not visible in the diff, on a caller that was
418
+ not read, or on a failure scenario that was imagined rather than
419
+ traced, is low confidence however plausible its prose sounds.
420
+ LLM reviewers systematically overstate certainty here; a
421
+ consumer thresholding on this attribute is relying on it being
422
+ lowered honestly.
423
+
424
+ This attribute has no schema default on purpose. When it is
425
+ absent, a consumer must treat the comment as falling below any
426
+ confidence floor it applies, i.e. absent never satisfies a
427
+ threshold.
428
+ </xs:documentation>
429
+ </xs:annotation>
430
+ </xs:attribute>
358
431
  </xs:complexType>
359
432
 
360
433
  <xs:complexType name="SuggestionType">
@@ -406,6 +479,8 @@ var XSD_SCHEMA = `<?xml version="1.0" encoding="UTF-8"?>
406
479
  </xs:attribute>
407
480
  </xs:complexType>
408
481
 
482
+ <!-- ===== Simple types ===== -->
483
+
409
484
  <xs:simpleType name="ChangeTypeEnum">
410
485
  <xs:annotation>
411
486
  <xs:documentation>
@@ -436,6 +511,93 @@ var XSD_SCHEMA = `<?xml version="1.0" encoding="UTF-8"?>
436
511
  </xs:restriction>
437
512
  </xs:simpleType>
438
513
 
514
+ <xs:simpleType name="SeverityEnum">
515
+ <xs:annotation>
516
+ <xs:documentation>
517
+ How consequential a finding is if it is real. Ordered from most to
518
+ least consequential: critical, major, minor, info.
519
+ </xs:documentation>
520
+ </xs:annotation>
521
+ <xs:restriction base="xs:string">
522
+ <xs:enumeration value="critical">
523
+ <xs:annotation>
524
+ <xs:documentation>
525
+ Causes data loss, a security hole, or a crash or corruption on a
526
+ path that real usage reaches. Shipping this is not acceptable.
527
+ </xs:documentation>
528
+ </xs:annotation>
529
+ </xs:enumeration>
530
+ <xs:enumeration value="major">
531
+ <xs:annotation>
532
+ <xs:documentation>
533
+ Produces wrong behaviour, or breaks a documented contract, on a
534
+ path that real usage reaches. The code does not do what it is
535
+ supposed to do, but nothing is destroyed and there is no security
536
+ impact.
537
+ </xs:documentation>
538
+ </xs:annotation>
539
+ </xs:enumeration>
540
+ <xs:enumeration value="minor">
541
+ <xs:annotation>
542
+ <xs:documentation>
543
+ Real but bounded: a mishandled edge case that is unlikely to be
544
+ hit, a missing test, a leak of something cheap, or a maintenance
545
+ hazard that will cost time later. Behaviour is correct today.
546
+ </xs:documentation>
547
+ </xs:annotation>
548
+ </xs:enumeration>
549
+ <xs:enumeration value="info">
550
+ <xs:annotation>
551
+ <xs:documentation>
552
+ No defect. Style, naming, phrasing, a question for the author, or
553
+ a note recorded for context. Nothing is wrong if this is never
554
+ acted on.
555
+ </xs:documentation>
556
+ </xs:annotation>
557
+ </xs:enumeration>
558
+ </xs:restriction>
559
+ </xs:simpleType>
560
+
561
+ <xs:simpleType name="ConfidenceEnum">
562
+ <xs:annotation>
563
+ <xs:documentation>
564
+ How sure the author is that a finding is real. Ordered from most to
565
+ least sure: high, medium, low.
566
+ </xs:documentation>
567
+ </xs:annotation>
568
+ <xs:restriction base="xs:string">
569
+ <xs:enumeration value="high">
570
+ <xs:annotation>
571
+ <xs:documentation>
572
+ The evidence is in the code that was read. The failure can be
573
+ traced from the diff itself, and no assumption about unseen code,
574
+ unseen callers, or unstated requirements is needed to reach it.
575
+ </xs:documentation>
576
+ </xs:annotation>
577
+ </xs:enumeration>
578
+ <xs:enumeration value="medium">
579
+ <xs:annotation>
580
+ <xs:documentation>
581
+ Likely real, but it rests on one assumption that was not verified,
582
+ such as how a caller behaves, what a dependency guarantees, or
583
+ what the intended requirement was. Stating that assumption in the
584
+ body is expected at this level.
585
+ </xs:documentation>
586
+ </xs:annotation>
587
+ </xs:enumeration>
588
+ <xs:enumeration value="low">
589
+ <xs:annotation>
590
+ <xs:documentation>
591
+ Speculative. The failure scenario was imagined rather than traced,
592
+ or the finding depends on a constraint the author invented, or the
593
+ author could not tell intent from the code. Worth a human's eyes,
594
+ not worth acting on unattended.
595
+ </xs:documentation>
596
+ </xs:annotation>
597
+ </xs:enumeration>
598
+ </xs:restriction>
599
+ </xs:simpleType>
600
+
439
601
  </xs:schema>`;
440
602
  function extFromMediaType(mediaType) {
441
603
  const map = {
@@ -479,7 +641,7 @@ async function serializeReview(state, outputFilePath) {
479
641
  try {
480
642
  const validationResult = await validateXML({
481
643
  xml: [{ fileName: "review.xml", contents: xml }],
482
- schema: [{ fileName: "self-review-v1.xsd", contents: XSD_SCHEMA }]
644
+ schema: [{ fileName: "self-review-v2.xsd", contents: XSD_SCHEMA }]
483
645
  });
484
646
  if (!validationResult.valid) {
485
647
  const errors = validationResult.errors || [];
@@ -515,7 +677,7 @@ function buildXml(state) {
515
677
  lines.push('<?xml version="1.0" encoding="UTF-8"?>');
516
678
  const sourceAttrs = buildSourceAttributes(state);
517
679
  lines.push(
518
- `<review xmlns="urn:self-review:v1" timestamp="${escapeXml(state.timestamp)}"${sourceAttrs}>`
680
+ `<review xmlns="urn:self-review:v2" timestamp="${escapeXml(state.timestamp)}"${sourceAttrs}>`
519
681
  );
520
682
  for (const file of state.files) {
521
683
  lines.push(...buildFileXml(file));
@@ -555,6 +717,12 @@ function buildCommentXml(comment) {
555
717
  if (comment.author) {
556
718
  attrs.push(`author="${escapeXml(comment.author)}"`);
557
719
  }
720
+ if (comment.severity) {
721
+ attrs.push(`severity="${comment.severity}"`);
722
+ }
723
+ if (comment.confidence) {
724
+ attrs.push(`confidence="${comment.confidence}"`);
725
+ }
558
726
  const attrStr = attrs.length > 0 ? " " + attrs.join(" ") : "";
559
727
  lines.push(` <comment${attrStr}>`);
560
728
  lines.push(` <body>${escapeXml(comment.body)}</body>`);
@@ -584,6 +752,8 @@ function escapeXml(str) {
584
752
  // src/xml-parser.ts
585
753
  import { readFileSync } from "fs";
586
754
  import { XMLParser } from "fast-xml-parser";
755
+ var SEVERITY_VALUES = ["critical", "major", "minor", "info"];
756
+ var CONFIDENCE_VALUES = ["high", "medium", "low"];
587
757
  function parseReviewXml(xmlPath) {
588
758
  try {
589
759
  const xmlContent = readFileSync(xmlPath, "utf-8");
@@ -625,7 +795,9 @@ function parseReviewXmlString(xmlContent) {
625
795
  body: comment.body || "",
626
796
  category: comment.category || "",
627
797
  suggestion: parseSuggestion(comment),
628
- author: comment["@_author"] ? String(comment["@_author"]) : void 0
798
+ author: comment["@_author"] ? String(comment["@_author"]) : void 0,
799
+ severity: parseEnumAttribute(comment["@_severity"], SEVERITY_VALUES),
800
+ confidence: parseEnumAttribute(comment["@_confidence"], CONFIDENCE_VALUES)
629
801
  };
630
802
  const commentAttachments = Array.isArray(comment.attachment) ? comment.attachment : comment.attachment ? [comment.attachment] : [];
631
803
  if (commentAttachments.length > 0) {
@@ -650,6 +822,11 @@ function parseReviewXmlString(xmlContent) {
650
822
  process.exit(1);
651
823
  }
652
824
  }
825
+ function parseEnumAttribute(raw, allowed) {
826
+ if (raw === void 0 || raw === null) return void 0;
827
+ const value = String(raw);
828
+ return allowed.includes(value) ? value : void 0;
829
+ }
653
830
  function parseSource(review) {
654
831
  const sourcePath = review["@_source-path"];
655
832
  if (sourcePath) {