@self-review/core 1.39.2 → 1.40.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
@@ -30,6 +30,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
30
30
  // src/index.ts
31
31
  var index_exports = {};
32
32
  __export(index_exports, {
33
+ GUIDE_XSD_SCHEMA: () => GUIDE_XSD_SCHEMA,
34
+ IMPLICIT_GUIDE_GROUP_NAME: () => IMPLICIT_GUIDE_GROUP_NAME,
33
35
  checkWritability: () => checkWritability,
34
36
  computePayloadStats: () => computePayloadStats,
35
37
  countTotalLines: () => countTotalLines,
@@ -49,8 +51,10 @@ __export(index_exports, {
49
51
  isPreviewableSvg: () => isPreviewableSvg,
50
52
  loadConfig: () => loadConfig,
51
53
  parseDiff: () => parseDiff,
54
+ parseGuideXml: () => parseGuideXml,
52
55
  parseReviewXml: () => parseReviewXml,
53
56
  parseReviewXmlString: () => parseReviewXmlString,
57
+ reconcileGuide: () => reconcileGuide,
54
58
  runGitDiff: () => runGitDiff,
55
59
  runGitDiffAsync: () => runGitDiffAsync,
56
60
  scanDirectory: () => scanDirectory,
@@ -945,6 +949,300 @@ function generateId() {
945
949
  return `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
946
950
  }
947
951
 
952
+ // src/guide-schema.ts
953
+ var GUIDE_XSD_SCHEMA = `<?xml version="1.0" encoding="UTF-8"?>
954
+ <xs:schema
955
+ xmlns:xs="http://www.w3.org/2001/XMLSchema"
956
+ xmlns:sg="urn:self-review-guide:v1"
957
+ targetNamespace="urn:self-review-guide:v1"
958
+ elementFormDefault="qualified"
959
+ >
960
+
961
+ <!--
962
+ self-review guide XML Schema v1
963
+ ===============================
964
+ Defines the walkthrough guide sidecar for the self-review application.
965
+ This schema is designed to be both machine-validated and fed to an LLM
966
+ so it can author valid guide documents from the schema alone.
967
+
968
+ Key concepts:
969
+ - A <guide> is a read-only orientation aid generated BEFORE a review
970
+ starts. It lives next to the review output file and is discovered by
971
+ convention; it is never written by the review UI.
972
+ - The optional <overview> is short Markdown prose shown before the
973
+ first file, orienting the reviewer to the change as a whole.
974
+ - Each <group> names a set of files that belong together (for example
975
+ "Core change", "Tests", "Generated/mechanical") and explains, in one
976
+ line, why they are grouped and where they sit in the reading order.
977
+ - Each <file> inside a group points at one diff file by its
978
+ repository-relative path and carries a one-line description of the
979
+ role that file plays in the change.
980
+
981
+ Ordering:
982
+ - Document order IS the reading order. Groups are presented in the
983
+ order they appear, and files within a group are presented in the
984
+ order they appear. There are no explicit ordering attributes; to
985
+ reorder, reorder the elements.
986
+
987
+ Presentation only, never suppression:
988
+ - This vocabulary labels and orders content; it cannot hide it. There
989
+ is deliberately no element or attribute that hides, collapses, or
990
+ marks a file as skippable, and none may be added to v1. Files in the
991
+ diff that no group mentions remain fully visible in an implicit
992
+ "Everything else" group; files mentioned here but absent from the
993
+ diff are silently ignored.
994
+
995
+ Tolerance:
996
+ - A missing, stale, or invalid guide degrades the consumer to its
997
+ normal ungrouped view. A guide can therefore never block or fail a
998
+ review, but an invalid guide is silently useless, so authors should
999
+ validate against this schema before writing the file.
1000
+ -->
1001
+
1002
+ <!-- ===== Root element ===== -->
1003
+
1004
+ <xs:element name="guide" type="sg:GuideType">
1005
+ <xs:annotation>
1006
+ <xs:documentation>
1007
+ Root element of a self-review walkthrough guide sidecar. Contains
1008
+ an optional overview followed by zero or more ordered groups.
1009
+ </xs:documentation>
1010
+ </xs:annotation>
1011
+ </xs:element>
1012
+
1013
+ <!-- ===== Complex types ===== -->
1014
+
1015
+ <xs:complexType name="GuideType">
1016
+ <xs:annotation>
1017
+ <xs:documentation>
1018
+ The whole walkthrough guide. The optional metadata attributes
1019
+ mirror the review schema's provenance attributes so a consumer can
1020
+ sanity-check that the guide was generated for the diff it is being
1021
+ shown next to; none of them are required and none affect
1022
+ presentation.
1023
+ </xs:documentation>
1024
+ </xs:annotation>
1025
+ <xs:sequence>
1026
+ <xs:element name="overview" type="xs:string" minOccurs="0">
1027
+ <xs:annotation>
1028
+ <xs:documentation>
1029
+ Review-level orientation prose shown before the first file.
1030
+ Markdown formatting is allowed, including fenced code blocks;
1031
+ a fenced code block labelled "mermaid" may be used for a
1032
+ diagram of the change.
1033
+ Keep it short: a few sentences saying what the change does and
1034
+ where to start reading, not a restatement of every file.
1035
+ </xs:documentation>
1036
+ </xs:annotation>
1037
+ </xs:element>
1038
+ <xs:element name="group" type="sg:GroupType" minOccurs="0" maxOccurs="unbounded">
1039
+ <xs:annotation>
1040
+ <xs:documentation>
1041
+ Ordered reading groups. The first group should hold the files
1042
+ the reviewer must understand first (the core of the change);
1043
+ later groups hold consequences, tests, and mechanical fallout.
1044
+ </xs:documentation>
1045
+ </xs:annotation>
1046
+ </xs:element>
1047
+ </xs:sequence>
1048
+ <xs:attribute name="timestamp" type="xs:dateTime" use="optional">
1049
+ <xs:annotation>
1050
+ <xs:documentation>
1051
+ ISO 8601 timestamp of when the guide was generated.
1052
+ </xs:documentation>
1053
+ </xs:annotation>
1054
+ </xs:attribute>
1055
+ <xs:attribute name="git-diff-args" type="xs:string" use="optional">
1056
+ <xs:annotation>
1057
+ <xs:documentation>
1058
+ The git diff arguments the guide was generated against.
1059
+ Example: "--staged", "main..feature-branch", "HEAD~3".
1060
+ Present only when the guide describes a git diff.
1061
+ </xs:documentation>
1062
+ </xs:annotation>
1063
+ </xs:attribute>
1064
+ <xs:attribute name="repository" type="xs:string" use="optional">
1065
+ <xs:annotation>
1066
+ <xs:documentation>
1067
+ Absolute path to the repository root the guide was generated in.
1068
+ Present only when the guide describes a git diff.
1069
+ </xs:documentation>
1070
+ </xs:annotation>
1071
+ </xs:attribute>
1072
+ </xs:complexType>
1073
+
1074
+ <xs:complexType name="GroupType">
1075
+ <xs:annotation>
1076
+ <xs:documentation>
1077
+ A named set of related files with a one-line rationale. Groups are
1078
+ labels for orientation, never suppressions: a consumer shows every
1079
+ group and every file in it. Position in the document is position
1080
+ in the reading order.
1081
+ </xs:documentation>
1082
+ </xs:annotation>
1083
+ <xs:sequence>
1084
+ <xs:element name="rationale" type="xs:string">
1085
+ <xs:annotation>
1086
+ <xs:documentation>
1087
+ One line explaining why these files form a group and what the
1088
+ reviewer should look for in them (e.g., "The retry wrapper
1089
+ everything else calls; read this first"). Plain text, a single
1090
+ sentence; no Markdown, no line breaks.
1091
+ </xs:documentation>
1092
+ </xs:annotation>
1093
+ </xs:element>
1094
+ <xs:element name="file" type="sg:FileEntryType" minOccurs="1" maxOccurs="unbounded">
1095
+ <xs:annotation>
1096
+ <xs:documentation>
1097
+ The files in this group, in reading order. A group must list
1098
+ at least one file; do not author empty placeholder groups.
1099
+ Every file in the diff may appear in at most one group, and
1100
+ files omitted from every group are not hidden \u2014 the consumer
1101
+ shows them in an implicit trailing "Everything else" group.
1102
+ </xs:documentation>
1103
+ </xs:annotation>
1104
+ </xs:element>
1105
+ </xs:sequence>
1106
+ <xs:attribute name="name" type="xs:string" use="required">
1107
+ <xs:annotation>
1108
+ <xs:documentation>
1109
+ Short display name for the group, e.g. "Core change", "Tests",
1110
+ "Generated/mechanical". Shown as the group heading in the file
1111
+ tree; keep it to a few words.
1112
+ </xs:documentation>
1113
+ </xs:annotation>
1114
+ </xs:attribute>
1115
+ </xs:complexType>
1116
+
1117
+ <xs:complexType name="FileEntryType">
1118
+ <xs:annotation>
1119
+ <xs:documentation>
1120
+ One file in a group. The path must match a file in the diff being
1121
+ reviewed; entries whose path matches nothing in the diff are
1122
+ silently dropped by the consumer, so a stale guide degrades
1123
+ instead of erroring.
1124
+ </xs:documentation>
1125
+ </xs:annotation>
1126
+ <xs:sequence>
1127
+ <xs:element name="description" type="xs:string">
1128
+ <xs:annotation>
1129
+ <xs:documentation>
1130
+ One line describing the role this file plays in the change
1131
+ (e.g., "Adds the retry wrapper that everything else calls").
1132
+ Plain text, a single sentence; no Markdown, no line breaks.
1133
+ </xs:documentation>
1134
+ </xs:annotation>
1135
+ </xs:element>
1136
+ </xs:sequence>
1137
+ <xs:attribute name="path" type="xs:string" use="required">
1138
+ <xs:annotation>
1139
+ <xs:documentation>
1140
+ File path relative to the repository root, using the same
1141
+ convention as review.xml file paths. For renamed files, use the
1142
+ new path.
1143
+ </xs:documentation>
1144
+ </xs:annotation>
1145
+ </xs:attribute>
1146
+ </xs:complexType>
1147
+
1148
+ </xs:schema>`;
1149
+
1150
+ // src/guide-parser.ts
1151
+ var import_fast_xml_parser2 = require("fast-xml-parser");
1152
+ var import_xmllint_wasm2 = require("xmllint-wasm");
1153
+ var IMPLICIT_GUIDE_GROUP_NAME = "Everything else";
1154
+ async function parseGuideXml(xmlContent) {
1155
+ try {
1156
+ const validationResult = await (0, import_xmllint_wasm2.validateXML)({
1157
+ xml: [{ fileName: "guide.xml", contents: xmlContent }],
1158
+ schema: [
1159
+ { fileName: "self-review-guide-v1.xsd", contents: GUIDE_XSD_SCHEMA }
1160
+ ]
1161
+ });
1162
+ if (!validationResult.valid) {
1163
+ const details = (validationResult.errors || []).map((err) => typeof err === "string" ? err : err.message).join("; ");
1164
+ return {
1165
+ ok: false,
1166
+ reason: `Guide XML does not conform to self-review-guide-v1 schema${details ? `: ${details}` : ""}`
1167
+ };
1168
+ }
1169
+ return { ok: true, guide: readGuide(xmlContent) };
1170
+ } catch (error) {
1171
+ const message = error instanceof Error ? error.message : String(error);
1172
+ return { ok: false, reason: `Failed to parse guide XML: ${message}` };
1173
+ }
1174
+ }
1175
+ function readGuide(xmlContent) {
1176
+ const parser = new import_fast_xml_parser2.XMLParser({
1177
+ ignoreAttributes: false,
1178
+ attributeNamePrefix: "@_",
1179
+ // Keep values verbatim: a description like "007" or an overview of
1180
+ // "true" must stay a string, not become a number or boolean.
1181
+ parseTagValue: false,
1182
+ parseAttributeValue: false,
1183
+ // A prefixed form (<sg:guide xmlns:sg="urn:self-review-guide:v1">) is
1184
+ // schema-valid, so reading must accept it too; without this the lookup
1185
+ // of `.guide` below finds nothing.
1186
+ removeNSPrefix: true
1187
+ });
1188
+ const root = parser.parse(xmlContent).guide;
1189
+ const guide = { groups: asArray(root.group).map(readGroup) };
1190
+ const overview = root.overview;
1191
+ if (typeof overview === "string" && overview !== "") {
1192
+ guide.overview = overview;
1193
+ }
1194
+ return guide;
1195
+ }
1196
+ function readGroup(raw) {
1197
+ const group = raw;
1198
+ return {
1199
+ name: String(group["@_name"]),
1200
+ rationale: String(group.rationale ?? ""),
1201
+ files: asArray(group.file).map(readFileEntry)
1202
+ };
1203
+ }
1204
+ function readFileEntry(raw) {
1205
+ const file = raw;
1206
+ return {
1207
+ path: String(file["@_path"]),
1208
+ description: String(file.description ?? "")
1209
+ };
1210
+ }
1211
+ function asArray(value) {
1212
+ if (value === void 0 || value === null) return [];
1213
+ return Array.isArray(value) ? value : [value];
1214
+ }
1215
+ function reconcileGuide(guide, diffFilePaths) {
1216
+ const diffPaths = new Set(diffFilePaths);
1217
+ const claimed = /* @__PURE__ */ new Set();
1218
+ const resolved = [];
1219
+ for (const group of guide.groups) {
1220
+ const files = [];
1221
+ for (const file of group.files) {
1222
+ if (!diffPaths.has(file.path) || claimed.has(file.path)) continue;
1223
+ claimed.add(file.path);
1224
+ files.push({ path: file.path, description: file.description });
1225
+ }
1226
+ if (files.length > 0) {
1227
+ resolved.push({
1228
+ name: group.name,
1229
+ rationale: group.rationale,
1230
+ implicit: false,
1231
+ files
1232
+ });
1233
+ }
1234
+ }
1235
+ const leftover = diffFilePaths.filter((path2) => !claimed.has(path2));
1236
+ if (leftover.length > 0) {
1237
+ resolved.push({
1238
+ name: IMPLICIT_GUIDE_GROUP_NAME,
1239
+ implicit: true,
1240
+ files: leftover.map((path2) => ({ path: path2 }))
1241
+ });
1242
+ }
1243
+ return resolved;
1244
+ }
1245
+
948
1246
  // src/git.ts
949
1247
  var import_child_process = require("child_process");
950
1248
  var import_util = require("util");
@@ -1379,6 +1677,9 @@ function loadYamlConfig(path2) {
1379
1677
  if ("output-file" in raw && typeof raw["output-file"] === "string" && raw["output-file"].length > 0) {
1380
1678
  config.outputFile = raw["output-file"];
1381
1679
  }
1680
+ if ("guide-file" in raw && typeof raw["guide-file"] === "string" && raw["guide-file"].length > 0) {
1681
+ config.guideFile = raw["guide-file"];
1682
+ }
1382
1683
  return config;
1383
1684
  }
1384
1685
  function mergeConfig(base, override) {
@@ -1556,6 +1857,8 @@ function getLanguageFromPath(filePath) {
1556
1857
  }
1557
1858
  // Annotate the CommonJS export names for ESM import in node:
1558
1859
  0 && (module.exports = {
1860
+ GUIDE_XSD_SCHEMA,
1861
+ IMPLICIT_GUIDE_GROUP_NAME,
1559
1862
  checkWritability,
1560
1863
  computePayloadStats,
1561
1864
  countTotalLines,
@@ -1575,8 +1878,10 @@ function getLanguageFromPath(filePath) {
1575
1878
  isPreviewableSvg,
1576
1879
  loadConfig,
1577
1880
  parseDiff,
1881
+ parseGuideXml,
1578
1882
  parseReviewXml,
1579
1883
  parseReviewXmlString,
1884
+ reconcileGuide,
1580
1885
  runGitDiff,
1581
1886
  runGitDiffAsync,
1582
1887
  scanDirectory,