@cluesmith/codev-core 3.1.9 → 3.2.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.
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Review-marker codec — the single, host-agnostic home for the on-disk `REVIEW`
|
|
3
|
+
* comment format and the transforms a rendered review surface needs.
|
|
4
|
+
*
|
|
5
|
+
* Background (#859): `@cluesmith/codev-artifact-canvas` renders Codev artifacts
|
|
6
|
+
* (specs/plans/reviews) and lets a reviewer add inline comments. A comment is
|
|
7
|
+
* serialized into the markdown as a positional HTML comment:
|
|
8
|
+
*
|
|
9
|
+
* <!-- REVIEW(@<author>): <text> -->
|
|
10
|
+
*
|
|
11
|
+
* written on the line **after** the block it annotates. There is no `line=N`
|
|
12
|
+
* attribute. The marker's *position in the file* is the entire line association:
|
|
13
|
+
* a marker annotates the nearest non-marker line above it (so a stack of
|
|
14
|
+
* comments on one block all resolve to that block). This convention
|
|
15
|
+
* matches both the existing VSCode editor Comments-API path
|
|
16
|
+
* (`packages/vscode/src/comments/plan-review.ts`) and the canvas package's own
|
|
17
|
+
* tested adapter contract, so the two authoring surfaces round-trip through the
|
|
18
|
+
* same bytes.
|
|
19
|
+
*
|
|
20
|
+
* This module lives in `core` (not in a host) because the convention is a
|
|
21
|
+
* cross-host contract: the VSCode host consumes it now, and the dashboard /
|
|
22
|
+
* future hosts consume the same functions so they cannot drift. It is pure
|
|
23
|
+
* (no `vscode`, no DOM, no I/O) and therefore safe in both Node and the browser.
|
|
24
|
+
*
|
|
25
|
+
* Hiding markers from the rendered body is NOT done here: the canvas renderer
|
|
26
|
+
* strips full-line HTML comments before parsing (keeping blocks intact and
|
|
27
|
+
* `data-line` accurate), so hosts pass raw document text straight through. This
|
|
28
|
+
* codec is purely the on-disk read/write convention (#1036 is fixed in the
|
|
29
|
+
* renderer, #1042).
|
|
30
|
+
*/
|
|
31
|
+
/**
|
|
32
|
+
* In-memory model of one review marker. Structurally matches
|
|
33
|
+
* `ReviewMarker` from `@cluesmith/codev-artifact-canvas` (kept as a local
|
|
34
|
+
* declaration so `core` does not depend on the React rendering package).
|
|
35
|
+
*/
|
|
36
|
+
export interface ReviewMarker {
|
|
37
|
+
author: string;
|
|
38
|
+
/** 0-based logical line the marker annotates (the line *above* the marker). */
|
|
39
|
+
line: number;
|
|
40
|
+
text: string;
|
|
41
|
+
/** Original on-disk marker text, for lossless round-tripping. */
|
|
42
|
+
raw: string;
|
|
43
|
+
/** Reserved for region anchors (unused in v1). */
|
|
44
|
+
lineRange?: {
|
|
45
|
+
start: number;
|
|
46
|
+
end: number;
|
|
47
|
+
};
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* Eligible artifact paths — the `+` affordance and the canvas editor are gated
|
|
51
|
+
* to these. Shared so the editor path and the canvas host agree on one rule.
|
|
52
|
+
*/
|
|
53
|
+
export declare const ELIGIBLE_PATH_REGEX: RegExp;
|
|
54
|
+
/** True if `fsPath` (forward-slash normalized or not) is a review-eligible artifact. */
|
|
55
|
+
export declare function isEligibleReviewPath(fsPath: string): boolean;
|
|
56
|
+
/** True if a single line is a review marker. */
|
|
57
|
+
export declare function isReviewMarkerLine(line: string): boolean;
|
|
58
|
+
/**
|
|
59
|
+
* Serialize a marker to its canonical on-disk form. The body is
|
|
60
|
+
* whitespace-normalized to a single line (markers are single-line by
|
|
61
|
+
* convention; the canvas/editor decorations assume one line). `indent` is
|
|
62
|
+
* prepended so a marker inside an indented list item keeps the list's
|
|
63
|
+
* indentation.
|
|
64
|
+
*/
|
|
65
|
+
export declare function serializeReviewMarker(author: string, body: string, indent?: string): string;
|
|
66
|
+
/**
|
|
67
|
+
* The file line a new marker is written to, given the 0-based line it annotates:
|
|
68
|
+
* the line *after* the annotated line. Encoded here so every caller (editor +
|
|
69
|
+
* canvas host) shares one definition of the convention and cannot drift.
|
|
70
|
+
*/
|
|
71
|
+
export declare function markerInsertionLine(annotatedLine: number): number;
|
|
72
|
+
/**
|
|
73
|
+
* Parse all review markers out of `text` into `ReviewMarker`s, mapping each to
|
|
74
|
+
* the 0-based logical line it annotates: the nearest line ABOVE the marker that
|
|
75
|
+
* is not itself a marker. Skipping over a run of stacked markers means several
|
|
76
|
+
* comments on one block all anchor to that block's start (the canvas renders
|
|
77
|
+
* them as a list) instead of each pointing at the marker above it. A marker, or
|
|
78
|
+
* a run of markers, at the very top of the file annotates nothing and is skipped.
|
|
79
|
+
*/
|
|
80
|
+
export declare function parseReviewMarkers(text: string): ReviewMarker[];
|
|
81
|
+
//# sourceMappingURL=review-markers.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"review-markers.d.ts","sourceRoot":"","sources":["../src/review-markers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,GAAG,EAAE,MAAM,CAAC;IACZ,kDAAkD;IAClD,SAAS,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CAC5C;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,QAAqC,CAAC;AAUtE,wFAAwF;AACxF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE5D;AAED,gDAAgD;AAChD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,SAAK,GAAG,MAAM,CAGvF;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,EAAE,CAY/D"}
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Review-marker codec — the single, host-agnostic home for the on-disk `REVIEW`
|
|
3
|
+
* comment format and the transforms a rendered review surface needs.
|
|
4
|
+
*
|
|
5
|
+
* Background (#859): `@cluesmith/codev-artifact-canvas` renders Codev artifacts
|
|
6
|
+
* (specs/plans/reviews) and lets a reviewer add inline comments. A comment is
|
|
7
|
+
* serialized into the markdown as a positional HTML comment:
|
|
8
|
+
*
|
|
9
|
+
* <!-- REVIEW(@<author>): <text> -->
|
|
10
|
+
*
|
|
11
|
+
* written on the line **after** the block it annotates. There is no `line=N`
|
|
12
|
+
* attribute. The marker's *position in the file* is the entire line association:
|
|
13
|
+
* a marker annotates the nearest non-marker line above it (so a stack of
|
|
14
|
+
* comments on one block all resolve to that block). This convention
|
|
15
|
+
* matches both the existing VSCode editor Comments-API path
|
|
16
|
+
* (`packages/vscode/src/comments/plan-review.ts`) and the canvas package's own
|
|
17
|
+
* tested adapter contract, so the two authoring surfaces round-trip through the
|
|
18
|
+
* same bytes.
|
|
19
|
+
*
|
|
20
|
+
* This module lives in `core` (not in a host) because the convention is a
|
|
21
|
+
* cross-host contract: the VSCode host consumes it now, and the dashboard /
|
|
22
|
+
* future hosts consume the same functions so they cannot drift. It is pure
|
|
23
|
+
* (no `vscode`, no DOM, no I/O) and therefore safe in both Node and the browser.
|
|
24
|
+
*
|
|
25
|
+
* Hiding markers from the rendered body is NOT done here: the canvas renderer
|
|
26
|
+
* strips full-line HTML comments before parsing (keeping blocks intact and
|
|
27
|
+
* `data-line` accurate), so hosts pass raw document text straight through. This
|
|
28
|
+
* codec is purely the on-disk read/write convention (#1036 is fixed in the
|
|
29
|
+
* renderer, #1042).
|
|
30
|
+
*/
|
|
31
|
+
/**
|
|
32
|
+
* Eligible artifact paths — the `+` affordance and the canvas editor are gated
|
|
33
|
+
* to these. Shared so the editor path and the canvas host agree on one rule.
|
|
34
|
+
*/
|
|
35
|
+
export const ELIGIBLE_PATH_REGEX = /\/codev\/(plans|specs|reviews)\//;
|
|
36
|
+
/**
|
|
37
|
+
* Per-line marker matcher. Capture groups: [1] indent, [2] author, [3] body.
|
|
38
|
+
* A marker occupies its own line by convention; the body is single-line
|
|
39
|
+
* (whitespace-normalized at write time). Tolerant of surrounding whitespace to
|
|
40
|
+
* stay compatible with markers authored by the editor path and by hand.
|
|
41
|
+
*/
|
|
42
|
+
const REVIEW_MARKER_RE = /^(\s*)<!--\s*REVIEW\s*\(@([^)]+)\)\s*:\s*([\s\S]*?)\s*-->\s*$/;
|
|
43
|
+
/** True if `fsPath` (forward-slash normalized or not) is a review-eligible artifact. */
|
|
44
|
+
export function isEligibleReviewPath(fsPath) {
|
|
45
|
+
return ELIGIBLE_PATH_REGEX.test(fsPath.replace(/\\/g, '/'));
|
|
46
|
+
}
|
|
47
|
+
/** True if a single line is a review marker. */
|
|
48
|
+
export function isReviewMarkerLine(line) {
|
|
49
|
+
return REVIEW_MARKER_RE.test(line);
|
|
50
|
+
}
|
|
51
|
+
/**
|
|
52
|
+
* Serialize a marker to its canonical on-disk form. The body is
|
|
53
|
+
* whitespace-normalized to a single line (markers are single-line by
|
|
54
|
+
* convention; the canvas/editor decorations assume one line). `indent` is
|
|
55
|
+
* prepended so a marker inside an indented list item keeps the list's
|
|
56
|
+
* indentation.
|
|
57
|
+
*/
|
|
58
|
+
export function serializeReviewMarker(author, body, indent = '') {
|
|
59
|
+
const normalized = body.replace(/\s+/g, ' ').trim();
|
|
60
|
+
return `${indent}<!-- REVIEW(@${author}): ${normalized} -->`;
|
|
61
|
+
}
|
|
62
|
+
/**
|
|
63
|
+
* The file line a new marker is written to, given the 0-based line it annotates:
|
|
64
|
+
* the line *after* the annotated line. Encoded here so every caller (editor +
|
|
65
|
+
* canvas host) shares one definition of the convention and cannot drift.
|
|
66
|
+
*/
|
|
67
|
+
export function markerInsertionLine(annotatedLine) {
|
|
68
|
+
return annotatedLine + 1;
|
|
69
|
+
}
|
|
70
|
+
/**
|
|
71
|
+
* Parse all review markers out of `text` into `ReviewMarker`s, mapping each to
|
|
72
|
+
* the 0-based logical line it annotates: the nearest line ABOVE the marker that
|
|
73
|
+
* is not itself a marker. Skipping over a run of stacked markers means several
|
|
74
|
+
* comments on one block all anchor to that block's start (the canvas renders
|
|
75
|
+
* them as a list) instead of each pointing at the marker above it. A marker, or
|
|
76
|
+
* a run of markers, at the very top of the file annotates nothing and is skipped.
|
|
77
|
+
*/
|
|
78
|
+
export function parseReviewMarkers(text) {
|
|
79
|
+
const out = [];
|
|
80
|
+
const lines = text.split('\n');
|
|
81
|
+
for (let i = 0; i < lines.length; i++) {
|
|
82
|
+
const m = REVIEW_MARKER_RE.exec(lines[i]);
|
|
83
|
+
if (!m) {
|
|
84
|
+
continue;
|
|
85
|
+
}
|
|
86
|
+
let anchor = i - 1;
|
|
87
|
+
while (anchor >= 0 && isReviewMarkerLine(lines[anchor])) {
|
|
88
|
+
anchor--;
|
|
89
|
+
}
|
|
90
|
+
if (anchor < 0) {
|
|
91
|
+
continue;
|
|
92
|
+
}
|
|
93
|
+
out.push({ author: m[2], line: anchor, text: m[3], raw: lines[i].trim() });
|
|
94
|
+
}
|
|
95
|
+
return out;
|
|
96
|
+
}
|
|
97
|
+
//# sourceMappingURL=review-markers.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"review-markers.js","sourceRoot":"","sources":["../src/review-markers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAkBH;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,kCAAkC,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,gBAAgB,GAAG,+DAA+D,CAAC;AAEzF,wFAAwF;AACxF,MAAM,UAAU,oBAAoB,CAAC,MAAc;IACjD,OAAO,mBAAmB,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC;AAC9D,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,OAAO,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAc,EAAE,IAAY,EAAE,MAAM,GAAG,EAAE;IAC7E,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACpD,OAAO,GAAG,MAAM,gBAAgB,MAAM,MAAM,UAAU,MAAM,CAAC;AAC/D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,aAAqB;IACvD,OAAO,aAAa,GAAG,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,MAAM,GAAG,GAAmB,EAAE,CAAC;IAC/B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,CAAC,GAAG,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1C,IAAI,CAAC,CAAC,EAAE,CAAC;YAAC,SAAS;QAAC,CAAC;QACrB,IAAI,MAAM,GAAG,CAAC,GAAG,CAAC,CAAC;QACnB,OAAO,MAAM,IAAI,CAAC,IAAI,kBAAkB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;YAAC,MAAM,EAAE,CAAC;QAAC,CAAC;QACtE,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;YAAC,SAAS;QAAC,CAAC;QAC7B,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IAC7E,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@cluesmith/codev-core",
|
|
3
|
-
"version": "3.
|
|
3
|
+
"version": "3.2.0",
|
|
4
4
|
"description": "Core runtime utilities for Codev — Tower client, auth, workspace helpers, escape buffer",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"exports": {
|
|
@@ -43,6 +43,10 @@
|
|
|
43
43
|
"./phase-grouping": {
|
|
44
44
|
"types": "./dist/phase-grouping.d.ts",
|
|
45
45
|
"default": "./dist/phase-grouping.js"
|
|
46
|
+
},
|
|
47
|
+
"./review-markers": {
|
|
48
|
+
"types": "./dist/review-markers.d.ts",
|
|
49
|
+
"default": "./dist/review-markers.js"
|
|
46
50
|
}
|
|
47
51
|
},
|
|
48
52
|
"files": [
|
|
@@ -52,7 +56,7 @@
|
|
|
52
56
|
"@types/node": "22.x",
|
|
53
57
|
"typescript": "^5.7.0",
|
|
54
58
|
"vitest": "^4.0.15",
|
|
55
|
-
"@cluesmith/codev-types": "3.
|
|
59
|
+
"@cluesmith/codev-types": "3.2.0"
|
|
56
60
|
},
|
|
57
61
|
"license": "Apache-2.0",
|
|
58
62
|
"scripts": {
|