@self-review/core 1.39.1 → 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.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { DiffFile, ReviewState, ReviewComment, DiffSource, AppConfig, PayloadStats } from '@self-review/types';
2
- export { AppConfig, Attachment, CategoryDef, ChangeType, CommentConfidence, CommentSeverity, DiffFile, DiffHunk, DiffLine, DiffLineType, DiffLoadPayload, DiffSource, ExpandContextRequest, ExpandContextResponse, FileReviewState, FindInPageRequest, FindInPageResult, ImageLoadResult, LineRange, OutputPathInfo, PayloadStats, ResumeLoadPayload, ReviewComment, ReviewState, Suggestion, VersionUpdateInfo } from '@self-review/types';
1
+ import { DiffFile, ReviewState, ReviewComment, DiffSource, ReviewGuide, ResolvedGuideGroup, AppConfig, PayloadStats } from '@self-review/types';
2
+ export { AppConfig, Attachment, CategoryDef, ChangeType, CommentConfidence, CommentSeverity, DiffFile, DiffHunk, DiffLine, DiffLineType, DiffLoadPayload, DiffSource, ExpandContextRequest, ExpandContextResponse, FileReviewState, FindInPageRequest, FindInPageResult, GuideFileEntry, GuideGroup, ImageLoadResult, LineRange, OutputPathInfo, PayloadStats, ResolvedGuideFile, ResolvedGuideGroup, ResumeLoadPayload, ReviewComment, ReviewGuide, ReviewState, Suggestion, VersionUpdateInfo } from '@self-review/types';
3
3
 
4
4
  declare function parseDiff(rawDiff: string): DiffFile[];
5
5
 
@@ -7,12 +7,49 @@ declare function serializeReview(state: ReviewState, outputFilePath: string): Pr
7
7
 
8
8
  interface ParsedReview {
9
9
  comments: ReviewComment[];
10
+ /** Paths of files the previous review marked as done (`viewed="true"`). */
11
+ viewedFiles: string[];
10
12
  gitDiffArgs: string;
11
13
  source: DiffSource;
12
14
  }
13
15
  declare function parseReviewXml(xmlPath: string): ParsedReview;
14
16
  declare function parseReviewXmlString(xmlContent: string): ParsedReview;
15
17
 
18
+ declare const GUIDE_XSD_SCHEMA = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<xs:schema\n xmlns:xs=\"http://www.w3.org/2001/XMLSchema\"\n xmlns:sg=\"urn:self-review-guide:v1\"\n targetNamespace=\"urn:self-review-guide:v1\"\n elementFormDefault=\"qualified\"\n>\n\n <!--\n self-review guide XML Schema v1\n ===============================\n Defines the walkthrough guide sidecar for the self-review application.\n This schema is designed to be both machine-validated and fed to an LLM\n so it can author valid guide documents from the schema alone.\n\n Key concepts:\n - A <guide> is a read-only orientation aid generated BEFORE a review\n starts. It lives next to the review output file and is discovered by\n convention; it is never written by the review UI.\n - The optional <overview> is short Markdown prose shown before the\n first file, orienting the reviewer to the change as a whole.\n - Each <group> names a set of files that belong together (for example\n \"Core change\", \"Tests\", \"Generated/mechanical\") and explains, in one\n line, why they are grouped and where they sit in the reading order.\n - Each <file> inside a group points at one diff file by its\n repository-relative path and carries a one-line description of the\n role that file plays in the change.\n\n Ordering:\n - Document order IS the reading order. Groups are presented in the\n order they appear, and files within a group are presented in the\n order they appear. There are no explicit ordering attributes; to\n reorder, reorder the elements.\n\n Presentation only, never suppression:\n - This vocabulary labels and orders content; it cannot hide it. There\n is deliberately no element or attribute that hides, collapses, or\n marks a file as skippable, and none may be added to v1. Files in the\n diff that no group mentions remain fully visible in an implicit\n \"Everything else\" group; files mentioned here but absent from the\n diff are silently ignored.\n\n Tolerance:\n - A missing, stale, or invalid guide degrades the consumer to its\n normal ungrouped view. A guide can therefore never block or fail a\n review, but an invalid guide is silently useless, so authors should\n validate against this schema before writing the file.\n -->\n\n <!-- ===== Root element ===== -->\n\n <xs:element name=\"guide\" type=\"sg:GuideType\">\n <xs:annotation>\n <xs:documentation>\n Root element of a self-review walkthrough guide sidecar. Contains\n an optional overview followed by zero or more ordered groups.\n </xs:documentation>\n </xs:annotation>\n </xs:element>\n\n <!-- ===== Complex types ===== -->\n\n <xs:complexType name=\"GuideType\">\n <xs:annotation>\n <xs:documentation>\n The whole walkthrough guide. The optional metadata attributes\n mirror the review schema's provenance attributes so a consumer can\n sanity-check that the guide was generated for the diff it is being\n shown next to; none of them are required and none affect\n presentation.\n </xs:documentation>\n </xs:annotation>\n <xs:sequence>\n <xs:element name=\"overview\" type=\"xs:string\" minOccurs=\"0\">\n <xs:annotation>\n <xs:documentation>\n Review-level orientation prose shown before the first file.\n Markdown formatting is allowed, including fenced code blocks;\n a fenced code block labelled \"mermaid\" may be used for a\n diagram of the change.\n Keep it short: a few sentences saying what the change does and\n where to start reading, not a restatement of every file.\n </xs:documentation>\n </xs:annotation>\n </xs:element>\n <xs:element name=\"group\" type=\"sg:GroupType\" minOccurs=\"0\" maxOccurs=\"unbounded\">\n <xs:annotation>\n <xs:documentation>\n Ordered reading groups. The first group should hold the files\n the reviewer must understand first (the core of the change);\n later groups hold consequences, tests, and mechanical fallout.\n </xs:documentation>\n </xs:annotation>\n </xs:element>\n </xs:sequence>\n <xs:attribute name=\"timestamp\" type=\"xs:dateTime\" use=\"optional\">\n <xs:annotation>\n <xs:documentation>\n ISO 8601 timestamp of when the guide was generated.\n </xs:documentation>\n </xs:annotation>\n </xs:attribute>\n <xs:attribute name=\"git-diff-args\" type=\"xs:string\" use=\"optional\">\n <xs:annotation>\n <xs:documentation>\n The git diff arguments the guide was generated against.\n Example: \"--staged\", \"main..feature-branch\", \"HEAD~3\".\n Present only when the guide describes a git diff.\n </xs:documentation>\n </xs:annotation>\n </xs:attribute>\n <xs:attribute name=\"repository\" type=\"xs:string\" use=\"optional\">\n <xs:annotation>\n <xs:documentation>\n Absolute path to the repository root the guide was generated in.\n Present only when the guide describes a git diff.\n </xs:documentation>\n </xs:annotation>\n </xs:attribute>\n </xs:complexType>\n\n <xs:complexType name=\"GroupType\">\n <xs:annotation>\n <xs:documentation>\n A named set of related files with a one-line rationale. Groups are\n labels for orientation, never suppressions: a consumer shows every\n group and every file in it. Position in the document is position\n in the reading order.\n </xs:documentation>\n </xs:annotation>\n <xs:sequence>\n <xs:element name=\"rationale\" type=\"xs:string\">\n <xs:annotation>\n <xs:documentation>\n One line explaining why these files form a group and what the\n reviewer should look for in them (e.g., \"The retry wrapper\n everything else calls; read this first\"). Plain text, a single\n sentence; no Markdown, no line breaks.\n </xs:documentation>\n </xs:annotation>\n </xs:element>\n <xs:element name=\"file\" type=\"sg:FileEntryType\" minOccurs=\"1\" maxOccurs=\"unbounded\">\n <xs:annotation>\n <xs:documentation>\n The files in this group, in reading order. A group must list\n at least one file; do not author empty placeholder groups.\n Every file in the diff may appear in at most one group, and\n files omitted from every group are not hidden \u2014 the consumer\n shows them in an implicit trailing \"Everything else\" group.\n </xs:documentation>\n </xs:annotation>\n </xs:element>\n </xs:sequence>\n <xs:attribute name=\"name\" type=\"xs:string\" use=\"required\">\n <xs:annotation>\n <xs:documentation>\n Short display name for the group, e.g. \"Core change\", \"Tests\",\n \"Generated/mechanical\". Shown as the group heading in the file\n tree; keep it to a few words.\n </xs:documentation>\n </xs:annotation>\n </xs:attribute>\n </xs:complexType>\n\n <xs:complexType name=\"FileEntryType\">\n <xs:annotation>\n <xs:documentation>\n One file in a group. The path must match a file in the diff being\n reviewed; entries whose path matches nothing in the diff are\n silently dropped by the consumer, so a stale guide degrades\n instead of erroring.\n </xs:documentation>\n </xs:annotation>\n <xs:sequence>\n <xs:element name=\"description\" type=\"xs:string\">\n <xs:annotation>\n <xs:documentation>\n One line describing the role this file plays in the change\n (e.g., \"Adds the retry wrapper that everything else calls\").\n Plain text, a single sentence; no Markdown, no line breaks.\n </xs:documentation>\n </xs:annotation>\n </xs:element>\n </xs:sequence>\n <xs:attribute name=\"path\" type=\"xs:string\" use=\"required\">\n <xs:annotation>\n <xs:documentation>\n File path relative to the repository root, using the same\n convention as review.xml file paths. For renamed files, use the\n new path.\n </xs:documentation>\n </xs:annotation>\n </xs:attribute>\n </xs:complexType>\n\n</xs:schema>";
19
+
20
+ /** Display name given to the derived trailing group of unmentioned files. */
21
+ declare const IMPLICIT_GUIDE_GROUP_NAME = "Everything else";
22
+ type GuideParseResult = {
23
+ ok: true;
24
+ guide: ReviewGuide;
25
+ } | {
26
+ ok: false;
27
+ reason: string;
28
+ };
29
+ /**
30
+ * Parse and validate a guide XML string.
31
+ *
32
+ * The document is validated against the embedded self-review-guide-v1 XSD
33
+ * (same xmllint-wasm tooling the review serializer uses) before being read,
34
+ * so a successful result is structurally guaranteed by the schema. Any
35
+ * defect — non-XML input, schema violations, validator failure — comes back
36
+ * as `{ ok: false, reason }`; this function never throws on bad input.
37
+ */
38
+ declare function parseGuideXml(xmlContent: string): Promise<GuideParseResult>;
39
+ /**
40
+ * Merge a parsed guide with the diff's file list into resolved display
41
+ * groups, tolerantly:
42
+ *
43
+ * - Guide entries whose path is not in the diff are dropped (stale guide);
44
+ * a group left with no surviving files is dropped entirely.
45
+ * - A file referenced by more than one group appears only in the first.
46
+ * - Diff files no group mentions land in a terminal implicit
47
+ * "Everything else" group, preserving the diff's file order, marked
48
+ * `implicit: true` so the UI can label it.
49
+ * - Guide group order and in-group file order are preserved.
50
+ */
51
+ declare function reconcileGuide(guide: ReviewGuide, diffFilePaths: string[]): ResolvedGuideGroup[];
52
+
16
53
  declare function runGitDiff(args: string[]): string;
17
54
  declare function getRepoRoot(): string;
18
55
  /**
@@ -120,4 +157,4 @@ declare function getRenderedTextMode(filePath: string): RenderedTextMode | null;
120
157
  declare function isPreviewableRenderedText(filePath: string): boolean;
121
158
  declare function getLanguageFromPath(filePath: string): string;
122
159
 
123
- export { type RenderedTextMode, checkWritability, computePayloadStats, countTotalLines, createIgnoreFilter, generateSyntheticDiffs, generateUntrackedDiffs, getGitDiffStats, getLanguageFromPath, getRenderedTextMode, getRepoRoot, getRepoRootAsync, getUntrackedFilesAsync, isHtmlFile, isMarkdownFile, isPreviewableImage, isPreviewableRenderedText, isPreviewableSvg, loadConfig, parseDiff, parseReviewXml, parseReviewXmlString, runGitDiff, runGitDiffAsync, scanDirectory, scanFile, serializeReview, validateGitAvailable };
160
+ export { GUIDE_XSD_SCHEMA, type GuideParseResult, IMPLICIT_GUIDE_GROUP_NAME, type RenderedTextMode, checkWritability, computePayloadStats, countTotalLines, createIgnoreFilter, generateSyntheticDiffs, generateUntrackedDiffs, getGitDiffStats, getLanguageFromPath, getRenderedTextMode, getRepoRoot, getRepoRootAsync, getUntrackedFilesAsync, isHtmlFile, isMarkdownFile, isPreviewableImage, isPreviewableRenderedText, isPreviewableSvg, loadConfig, parseDiff, parseGuideXml, parseReviewXml, parseReviewXmlString, reconcileGuide, runGitDiff, runGitDiffAsync, scanDirectory, scanFile, serializeReview, validateGitAvailable };
package/dist/index.js CHANGED
@@ -782,10 +782,14 @@ function parseReviewXmlString(xmlContent) {
782
782
  const gitDiffArgs = review["@_git-diff-args"] || "";
783
783
  const source = parseSource(review);
784
784
  const comments = [];
785
+ const viewedFiles = [];
785
786
  const files = Array.isArray(review.file) ? review.file : review.file ? [review.file] : [];
786
787
  for (const file of files) {
787
788
  const filePath = file["@_path"];
788
789
  if (!filePath) continue;
790
+ if (parseViewed(file["@_viewed"])) {
791
+ viewedFiles.push(String(filePath));
792
+ }
789
793
  const fileComments = Array.isArray(file.comment) ? file.comment : file.comment ? [file.comment] : [];
790
794
  for (const comment of fileComments) {
791
795
  const reviewComment = {
@@ -812,7 +816,7 @@ function parseReviewXmlString(xmlContent) {
812
816
  comments.push(reviewComment);
813
817
  }
814
818
  }
815
- return { comments, gitDiffArgs, source };
819
+ return { comments, viewedFiles, gitDiffArgs, source };
816
820
  } catch (error) {
817
821
  if (error instanceof Error) {
818
822
  console.error(`Error parsing XML: ${error.message}`);
@@ -827,6 +831,9 @@ function parseEnumAttribute(raw, allowed) {
827
831
  const value = String(raw);
828
832
  return allowed.includes(value) ? value : void 0;
829
833
  }
834
+ function parseViewed(raw) {
835
+ return raw === true || String(raw) === "true";
836
+ }
830
837
  function parseSource(review) {
831
838
  const sourcePath = review["@_source-path"];
832
839
  if (sourcePath) {
@@ -876,6 +883,300 @@ function generateId() {
876
883
  return `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
877
884
  }
878
885
 
886
+ // src/guide-schema.ts
887
+ var GUIDE_XSD_SCHEMA = `<?xml version="1.0" encoding="UTF-8"?>
888
+ <xs:schema
889
+ xmlns:xs="http://www.w3.org/2001/XMLSchema"
890
+ xmlns:sg="urn:self-review-guide:v1"
891
+ targetNamespace="urn:self-review-guide:v1"
892
+ elementFormDefault="qualified"
893
+ >
894
+
895
+ <!--
896
+ self-review guide XML Schema v1
897
+ ===============================
898
+ Defines the walkthrough guide sidecar for the self-review application.
899
+ This schema is designed to be both machine-validated and fed to an LLM
900
+ so it can author valid guide documents from the schema alone.
901
+
902
+ Key concepts:
903
+ - A <guide> is a read-only orientation aid generated BEFORE a review
904
+ starts. It lives next to the review output file and is discovered by
905
+ convention; it is never written by the review UI.
906
+ - The optional <overview> is short Markdown prose shown before the
907
+ first file, orienting the reviewer to the change as a whole.
908
+ - Each <group> names a set of files that belong together (for example
909
+ "Core change", "Tests", "Generated/mechanical") and explains, in one
910
+ line, why they are grouped and where they sit in the reading order.
911
+ - Each <file> inside a group points at one diff file by its
912
+ repository-relative path and carries a one-line description of the
913
+ role that file plays in the change.
914
+
915
+ Ordering:
916
+ - Document order IS the reading order. Groups are presented in the
917
+ order they appear, and files within a group are presented in the
918
+ order they appear. There are no explicit ordering attributes; to
919
+ reorder, reorder the elements.
920
+
921
+ Presentation only, never suppression:
922
+ - This vocabulary labels and orders content; it cannot hide it. There
923
+ is deliberately no element or attribute that hides, collapses, or
924
+ marks a file as skippable, and none may be added to v1. Files in the
925
+ diff that no group mentions remain fully visible in an implicit
926
+ "Everything else" group; files mentioned here but absent from the
927
+ diff are silently ignored.
928
+
929
+ Tolerance:
930
+ - A missing, stale, or invalid guide degrades the consumer to its
931
+ normal ungrouped view. A guide can therefore never block or fail a
932
+ review, but an invalid guide is silently useless, so authors should
933
+ validate against this schema before writing the file.
934
+ -->
935
+
936
+ <!-- ===== Root element ===== -->
937
+
938
+ <xs:element name="guide" type="sg:GuideType">
939
+ <xs:annotation>
940
+ <xs:documentation>
941
+ Root element of a self-review walkthrough guide sidecar. Contains
942
+ an optional overview followed by zero or more ordered groups.
943
+ </xs:documentation>
944
+ </xs:annotation>
945
+ </xs:element>
946
+
947
+ <!-- ===== Complex types ===== -->
948
+
949
+ <xs:complexType name="GuideType">
950
+ <xs:annotation>
951
+ <xs:documentation>
952
+ The whole walkthrough guide. The optional metadata attributes
953
+ mirror the review schema's provenance attributes so a consumer can
954
+ sanity-check that the guide was generated for the diff it is being
955
+ shown next to; none of them are required and none affect
956
+ presentation.
957
+ </xs:documentation>
958
+ </xs:annotation>
959
+ <xs:sequence>
960
+ <xs:element name="overview" type="xs:string" minOccurs="0">
961
+ <xs:annotation>
962
+ <xs:documentation>
963
+ Review-level orientation prose shown before the first file.
964
+ Markdown formatting is allowed, including fenced code blocks;
965
+ a fenced code block labelled "mermaid" may be used for a
966
+ diagram of the change.
967
+ Keep it short: a few sentences saying what the change does and
968
+ where to start reading, not a restatement of every file.
969
+ </xs:documentation>
970
+ </xs:annotation>
971
+ </xs:element>
972
+ <xs:element name="group" type="sg:GroupType" minOccurs="0" maxOccurs="unbounded">
973
+ <xs:annotation>
974
+ <xs:documentation>
975
+ Ordered reading groups. The first group should hold the files
976
+ the reviewer must understand first (the core of the change);
977
+ later groups hold consequences, tests, and mechanical fallout.
978
+ </xs:documentation>
979
+ </xs:annotation>
980
+ </xs:element>
981
+ </xs:sequence>
982
+ <xs:attribute name="timestamp" type="xs:dateTime" use="optional">
983
+ <xs:annotation>
984
+ <xs:documentation>
985
+ ISO 8601 timestamp of when the guide was generated.
986
+ </xs:documentation>
987
+ </xs:annotation>
988
+ </xs:attribute>
989
+ <xs:attribute name="git-diff-args" type="xs:string" use="optional">
990
+ <xs:annotation>
991
+ <xs:documentation>
992
+ The git diff arguments the guide was generated against.
993
+ Example: "--staged", "main..feature-branch", "HEAD~3".
994
+ Present only when the guide describes a git diff.
995
+ </xs:documentation>
996
+ </xs:annotation>
997
+ </xs:attribute>
998
+ <xs:attribute name="repository" type="xs:string" use="optional">
999
+ <xs:annotation>
1000
+ <xs:documentation>
1001
+ Absolute path to the repository root the guide was generated in.
1002
+ Present only when the guide describes a git diff.
1003
+ </xs:documentation>
1004
+ </xs:annotation>
1005
+ </xs:attribute>
1006
+ </xs:complexType>
1007
+
1008
+ <xs:complexType name="GroupType">
1009
+ <xs:annotation>
1010
+ <xs:documentation>
1011
+ A named set of related files with a one-line rationale. Groups are
1012
+ labels for orientation, never suppressions: a consumer shows every
1013
+ group and every file in it. Position in the document is position
1014
+ in the reading order.
1015
+ </xs:documentation>
1016
+ </xs:annotation>
1017
+ <xs:sequence>
1018
+ <xs:element name="rationale" type="xs:string">
1019
+ <xs:annotation>
1020
+ <xs:documentation>
1021
+ One line explaining why these files form a group and what the
1022
+ reviewer should look for in them (e.g., "The retry wrapper
1023
+ everything else calls; read this first"). Plain text, a single
1024
+ sentence; no Markdown, no line breaks.
1025
+ </xs:documentation>
1026
+ </xs:annotation>
1027
+ </xs:element>
1028
+ <xs:element name="file" type="sg:FileEntryType" minOccurs="1" maxOccurs="unbounded">
1029
+ <xs:annotation>
1030
+ <xs:documentation>
1031
+ The files in this group, in reading order. A group must list
1032
+ at least one file; do not author empty placeholder groups.
1033
+ Every file in the diff may appear in at most one group, and
1034
+ files omitted from every group are not hidden \u2014 the consumer
1035
+ shows them in an implicit trailing "Everything else" group.
1036
+ </xs:documentation>
1037
+ </xs:annotation>
1038
+ </xs:element>
1039
+ </xs:sequence>
1040
+ <xs:attribute name="name" type="xs:string" use="required">
1041
+ <xs:annotation>
1042
+ <xs:documentation>
1043
+ Short display name for the group, e.g. "Core change", "Tests",
1044
+ "Generated/mechanical". Shown as the group heading in the file
1045
+ tree; keep it to a few words.
1046
+ </xs:documentation>
1047
+ </xs:annotation>
1048
+ </xs:attribute>
1049
+ </xs:complexType>
1050
+
1051
+ <xs:complexType name="FileEntryType">
1052
+ <xs:annotation>
1053
+ <xs:documentation>
1054
+ One file in a group. The path must match a file in the diff being
1055
+ reviewed; entries whose path matches nothing in the diff are
1056
+ silently dropped by the consumer, so a stale guide degrades
1057
+ instead of erroring.
1058
+ </xs:documentation>
1059
+ </xs:annotation>
1060
+ <xs:sequence>
1061
+ <xs:element name="description" type="xs:string">
1062
+ <xs:annotation>
1063
+ <xs:documentation>
1064
+ One line describing the role this file plays in the change
1065
+ (e.g., "Adds the retry wrapper that everything else calls").
1066
+ Plain text, a single sentence; no Markdown, no line breaks.
1067
+ </xs:documentation>
1068
+ </xs:annotation>
1069
+ </xs:element>
1070
+ </xs:sequence>
1071
+ <xs:attribute name="path" type="xs:string" use="required">
1072
+ <xs:annotation>
1073
+ <xs:documentation>
1074
+ File path relative to the repository root, using the same
1075
+ convention as review.xml file paths. For renamed files, use the
1076
+ new path.
1077
+ </xs:documentation>
1078
+ </xs:annotation>
1079
+ </xs:attribute>
1080
+ </xs:complexType>
1081
+
1082
+ </xs:schema>`;
1083
+
1084
+ // src/guide-parser.ts
1085
+ import { XMLParser as XMLParser2 } from "fast-xml-parser";
1086
+ import { validateXML as validateXML2 } from "xmllint-wasm";
1087
+ var IMPLICIT_GUIDE_GROUP_NAME = "Everything else";
1088
+ async function parseGuideXml(xmlContent) {
1089
+ try {
1090
+ const validationResult = await validateXML2({
1091
+ xml: [{ fileName: "guide.xml", contents: xmlContent }],
1092
+ schema: [
1093
+ { fileName: "self-review-guide-v1.xsd", contents: GUIDE_XSD_SCHEMA }
1094
+ ]
1095
+ });
1096
+ if (!validationResult.valid) {
1097
+ const details = (validationResult.errors || []).map((err) => typeof err === "string" ? err : err.message).join("; ");
1098
+ return {
1099
+ ok: false,
1100
+ reason: `Guide XML does not conform to self-review-guide-v1 schema${details ? `: ${details}` : ""}`
1101
+ };
1102
+ }
1103
+ return { ok: true, guide: readGuide(xmlContent) };
1104
+ } catch (error) {
1105
+ const message = error instanceof Error ? error.message : String(error);
1106
+ return { ok: false, reason: `Failed to parse guide XML: ${message}` };
1107
+ }
1108
+ }
1109
+ function readGuide(xmlContent) {
1110
+ const parser = new XMLParser2({
1111
+ ignoreAttributes: false,
1112
+ attributeNamePrefix: "@_",
1113
+ // Keep values verbatim: a description like "007" or an overview of
1114
+ // "true" must stay a string, not become a number or boolean.
1115
+ parseTagValue: false,
1116
+ parseAttributeValue: false,
1117
+ // A prefixed form (<sg:guide xmlns:sg="urn:self-review-guide:v1">) is
1118
+ // schema-valid, so reading must accept it too; without this the lookup
1119
+ // of `.guide` below finds nothing.
1120
+ removeNSPrefix: true
1121
+ });
1122
+ const root = parser.parse(xmlContent).guide;
1123
+ const guide = { groups: asArray(root.group).map(readGroup) };
1124
+ const overview = root.overview;
1125
+ if (typeof overview === "string" && overview !== "") {
1126
+ guide.overview = overview;
1127
+ }
1128
+ return guide;
1129
+ }
1130
+ function readGroup(raw) {
1131
+ const group = raw;
1132
+ return {
1133
+ name: String(group["@_name"]),
1134
+ rationale: String(group.rationale ?? ""),
1135
+ files: asArray(group.file).map(readFileEntry)
1136
+ };
1137
+ }
1138
+ function readFileEntry(raw) {
1139
+ const file = raw;
1140
+ return {
1141
+ path: String(file["@_path"]),
1142
+ description: String(file.description ?? "")
1143
+ };
1144
+ }
1145
+ function asArray(value) {
1146
+ if (value === void 0 || value === null) return [];
1147
+ return Array.isArray(value) ? value : [value];
1148
+ }
1149
+ function reconcileGuide(guide, diffFilePaths) {
1150
+ const diffPaths = new Set(diffFilePaths);
1151
+ const claimed = /* @__PURE__ */ new Set();
1152
+ const resolved = [];
1153
+ for (const group of guide.groups) {
1154
+ const files = [];
1155
+ for (const file of group.files) {
1156
+ if (!diffPaths.has(file.path) || claimed.has(file.path)) continue;
1157
+ claimed.add(file.path);
1158
+ files.push({ path: file.path, description: file.description });
1159
+ }
1160
+ if (files.length > 0) {
1161
+ resolved.push({
1162
+ name: group.name,
1163
+ rationale: group.rationale,
1164
+ implicit: false,
1165
+ files
1166
+ });
1167
+ }
1168
+ }
1169
+ const leftover = diffFilePaths.filter((path2) => !claimed.has(path2));
1170
+ if (leftover.length > 0) {
1171
+ resolved.push({
1172
+ name: IMPLICIT_GUIDE_GROUP_NAME,
1173
+ implicit: true,
1174
+ files: leftover.map((path2) => ({ path: path2 }))
1175
+ });
1176
+ }
1177
+ return resolved;
1178
+ }
1179
+
879
1180
  // src/git.ts
880
1181
  import { execSync, exec } from "child_process";
881
1182
  import { promisify } from "util";
@@ -1310,6 +1611,9 @@ function loadYamlConfig(path2) {
1310
1611
  if ("output-file" in raw && typeof raw["output-file"] === "string" && raw["output-file"].length > 0) {
1311
1612
  config.outputFile = raw["output-file"];
1312
1613
  }
1614
+ if ("guide-file" in raw && typeof raw["guide-file"] === "string" && raw["guide-file"].length > 0) {
1615
+ config.guideFile = raw["guide-file"];
1616
+ }
1313
1617
  return config;
1314
1618
  }
1315
1619
  function mergeConfig(base, override) {
@@ -1486,6 +1790,8 @@ function getLanguageFromPath(filePath) {
1486
1790
  return langMap[ext] || "plaintext";
1487
1791
  }
1488
1792
  export {
1793
+ GUIDE_XSD_SCHEMA,
1794
+ IMPLICIT_GUIDE_GROUP_NAME,
1489
1795
  checkWritability,
1490
1796
  computePayloadStats,
1491
1797
  countTotalLines,
@@ -1505,8 +1811,10 @@ export {
1505
1811
  isPreviewableSvg,
1506
1812
  loadConfig,
1507
1813
  parseDiff,
1814
+ parseGuideXml,
1508
1815
  parseReviewXml,
1509
1816
  parseReviewXmlString,
1817
+ reconcileGuide,
1510
1818
  runGitDiff,
1511
1819
  runGitDiffAsync,
1512
1820
  scanDirectory,