vouchington-tooling 0.85.3 → 0.86.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.
@@ -6,7 +6,7 @@ export declare class DetailsScope {
6
6
  private readonly markdown;
7
7
  constructor(markdown: string);
8
8
  get visible(): boolean;
9
- acceptHtml(html: string, startOffset: number): void;
9
+ acceptHtml(html: string, startOffset: number, onVisibleFragment?: (value: string, offset: number) => void): void;
10
10
  finish(): void;
11
11
  private acceptTag;
12
12
  private problem;
@@ -9,15 +9,24 @@ export class DetailsScope {
9
9
  get visible() {
10
10
  return this.frames.length === 0;
11
11
  }
12
- acceptHtml(html, startOffset) {
12
+ acceptHtml(html, startOffset, onVisibleFragment) {
13
13
  const tokens = /<!--[\s\S]*?(?:-->|$)|<\/?[a-z][a-z\d:-]*(?:[^"'<>]|"[^"]*"|'[^']*')*>/giu;
14
+ let end = 0;
15
+ const emit = (value, offset) => {
16
+ if (this.visible && value.trim())
17
+ onVisibleFragment?.(value, offset);
18
+ };
14
19
  for (const token of html.matchAll(tokens)) {
20
+ emit(html.slice(end, token.index), startOffset + end);
21
+ end = token.index + token[0].length;
15
22
  if (token[0].startsWith('<!--'))
16
23
  continue;
17
24
  const tag = /^<(\/?)([a-z][a-z\d:-]*)/iu.exec(token[0]);
18
25
  const name = tag[2].toLowerCase();
19
- if (name !== 'details' && name !== 'summary')
26
+ if (name !== 'details' && name !== 'summary') {
27
+ emit(token[0], startOffset + token.index);
20
28
  continue;
29
+ }
21
30
  const line = this.markdown.slice(0, startOffset + token.index).split('\n').length;
22
31
  if (/\/\s*>$/u.test(token[0])) {
23
32
  this.problem(line, `${tag[2]} cannot be self-closing`);
@@ -25,6 +34,7 @@ export class DetailsScope {
25
34
  }
26
35
  this.acceptTag(name, tag[1] === '/', line);
27
36
  }
37
+ emit(html.slice(end), startOffset + end);
28
38
  }
29
39
  finish() {
30
40
  for (const frame of this.frames)
@@ -8,5 +8,7 @@ export type { MarkdownVisibleSection, MarkdownSectionsDiagnostic, MarkdownSectio
8
8
  export { markdownSectionBetweenHeadings } from './sections.mts';
9
9
  export { extractMarkdownTables, parseMarkdownTables } from './tables.mts';
10
10
  export { markdownNodeText } from './text.mts';
11
+ export { parseVisibleMarkdownContent } from './visible-content.mts';
12
+ export type { MarkdownVisibleBlock, MarkdownVisibleContent } from './visible-content-types.mts';
11
13
  export { hasUncheckedMarkdownTask } from './tasks.mts';
12
14
  export type { LooseMarkdownTableRow, LooseMarkdownTableRowsOptions, MarkdownNode, MarkdownHtmlBlockType, MarkdownHtmlFact, MarkdownSourcePosition, MarkdownSourceSpan, MarkdownSection, MarkdownSectionOptions, MarkdownTableRow, MarkdownTextOptions, ParseMarkdownTablesOptions, PositionedMarkdownTable, } from './types.mts';
@@ -7,4 +7,5 @@ export { validateMarkdownSections } from "./validate-sections.mjs";
7
7
  export { markdownSectionBetweenHeadings } from "./sections.mjs";
8
8
  export { extractMarkdownTables, parseMarkdownTables } from "./tables.mjs";
9
9
  export { markdownNodeText } from "./text.mjs";
10
+ export { parseVisibleMarkdownContent } from "./visible-content.mjs";
10
11
  export { hasUncheckedMarkdownTask } from "./tasks.mjs";
@@ -0,0 +1,40 @@
1
+ import type { MarkdownSectionsDiagnostic } from './document-types.mts';
2
+ import type { MarkdownSourcePosition } from './types.mts';
3
+ type PositionedBlock = {
4
+ position: MarkdownSourcePosition;
5
+ };
6
+ /** Source-backed facts from content outside every details disclosure. */
7
+ export type MarkdownVisibleBlock = (PositionedBlock & {
8
+ kind: 'heading';
9
+ depth: number;
10
+ text: string;
11
+ }) | (PositionedBlock & {
12
+ kind: 'paragraph';
13
+ text: string;
14
+ }) | (PositionedBlock & {
15
+ kind: 'list-item';
16
+ ordered: boolean;
17
+ text: string;
18
+ }) | (PositionedBlock & {
19
+ kind: 'table';
20
+ headers: string[];
21
+ rows: Array<{
22
+ cells: string[];
23
+ position: MarkdownSourcePosition;
24
+ }>;
25
+ }) | (PositionedBlock & {
26
+ kind: 'fenced-code';
27
+ language: string | null;
28
+ value: string;
29
+ }) | (PositionedBlock & {
30
+ kind: 'raw-html';
31
+ block: boolean;
32
+ value: string;
33
+ });
34
+ export type MarkdownVisibleContent = {
35
+ /** Visible prose in source order, counted once; code, images, comments, and HTML are excluded. */
36
+ text: string;
37
+ blocks: MarkdownVisibleBlock[];
38
+ diagnostics: MarkdownSectionsDiagnostic[];
39
+ };
40
+ export {};
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,3 @@
1
+ import type { MarkdownVisibleContent } from './visible-content-types.mts';
2
+ /** Parses source-positioned, visible Markdown facts without interpreting prose semantics. */
3
+ export declare function parseVisibleMarkdownContent(markdown: string): MarkdownVisibleContent;
@@ -0,0 +1,114 @@
1
+ import { parseGfmMarkdown } from "./ast.mjs";
2
+ import { DetailsScope } from "./details-scope.mjs";
3
+ const normalized = (value) => value.replace(/\s+/gu, ' ').trim();
4
+ const positionOf = (node) => node.position;
5
+ /** Parses source-positioned, visible Markdown facts without interpreting prose semantics. */
6
+ export function parseVisibleMarkdownContent(markdown) {
7
+ const blocks = [];
8
+ const scope = new DetailsScope(markdown);
9
+ const acceptHtml = (node, block) => {
10
+ const fragments = [];
11
+ scope.acceptHtml(node.value, node.position.start.offset, (value) => fragments.push(value));
12
+ // Raw HTML may render text that the Markdown AST cannot measure. Surface it for callers to
13
+ // reject in governed sections; inline tags retain their adjacent AST text nodes instead.
14
+ if (fragments.length)
15
+ blocks.push({
16
+ kind: 'raw-html',
17
+ block,
18
+ value: fragments.join(''),
19
+ position: positionOf(node),
20
+ });
21
+ };
22
+ const inlineText = (node) => {
23
+ if (node.type === 'html') {
24
+ acceptHtml(node, false);
25
+ return '';
26
+ }
27
+ if (node.type === 'image' || node.type === 'imageReference' || node.type === 'inlineCode')
28
+ return '';
29
+ if (node.type === 'text')
30
+ return scope.visible ? node.value : '';
31
+ if (node.type === 'break')
32
+ return scope.visible ? ' ' : '';
33
+ if (!('children' in node))
34
+ return '';
35
+ return node.children.map(inlineText).join('');
36
+ };
37
+ const visit = (node, ordered = false) => {
38
+ if (node.type === 'html') {
39
+ acceptHtml(node, true);
40
+ return;
41
+ }
42
+ if (node.type === 'code') {
43
+ const offset = positionOf(node).start.offset;
44
+ if (scope.visible && /^(?:`{3,}|~{3,})/u.test(markdown.slice(offset))) {
45
+ blocks.push({
46
+ kind: 'fenced-code',
47
+ language: node.lang ?? null,
48
+ value: node.value,
49
+ position: positionOf(node),
50
+ });
51
+ }
52
+ return;
53
+ }
54
+ if (node.type === 'heading' || node.type === 'paragraph') {
55
+ const text = normalized(node.children.map(inlineText).join(''));
56
+ if (text) {
57
+ if (node.type === 'heading')
58
+ blocks.push({ kind: 'heading', depth: node.depth, text, position: positionOf(node) });
59
+ else
60
+ blocks.push({ kind: 'paragraph', text, position: positionOf(node) });
61
+ }
62
+ return;
63
+ }
64
+ if (node.type === 'listItem') {
65
+ const pieces = [];
66
+ for (const child of node.children) {
67
+ if (child.type === 'paragraph')
68
+ pieces.push(inlineText(child));
69
+ else
70
+ visit(child);
71
+ }
72
+ const text = normalized(pieces.join(' '));
73
+ if (text)
74
+ blocks.push({ kind: 'list-item', ordered, text, position: positionOf(node) });
75
+ return;
76
+ }
77
+ if (node.type === 'list') {
78
+ for (const child of node.children)
79
+ visit(child, node.ordered === true);
80
+ return;
81
+ }
82
+ if (node.type === 'table') {
83
+ const rows = node.children.map((row) => ({
84
+ cells: row.children.map((cell) => normalized(inlineText(cell))),
85
+ position: positionOf(row),
86
+ }));
87
+ if (rows.some((row) => row.cells.some(Boolean))) {
88
+ blocks.push({
89
+ kind: 'table',
90
+ headers: rows[0].cells,
91
+ rows: rows.slice(1),
92
+ position: positionOf(node),
93
+ });
94
+ }
95
+ return;
96
+ }
97
+ if (!('children' in node))
98
+ return;
99
+ for (const child of node.children)
100
+ visit(child);
101
+ };
102
+ visit(parseGfmMarkdown(markdown));
103
+ scope.finish();
104
+ blocks.sort((a, b) => a.position.start.offset - b.position.start.offset);
105
+ const text = blocks
106
+ .flatMap((block) => {
107
+ if (block.kind === 'table')
108
+ return [...block.headers, ...block.rows.flatMap((row) => row.cells)];
109
+ return 'text' in block ? [block.text] : [];
110
+ })
111
+ .filter(Boolean)
112
+ .join('\n');
113
+ return { text, blocks, diagnostics: scope.diagnostics };
114
+ }
@@ -12,9 +12,10 @@ export type PullRequestProvenance = {
12
12
  };
13
13
  /**
14
14
  * The pull request body: the Summary, Impact, Related issues and Details sections followed by the
15
- * provenance lines. With `noSourceIssue` the Related issues section ends with `noSourceStatement`
16
- * (default {@link defaultNoSourceStatement}), after any `Refs` lines, instead of `- None`. Pure;
17
- * the caller supplies the device and worktree facts.
15
+ * provenance lines, collapsed in a Provenance disclosure because they serve audits, not reviewers.
16
+ * With `noSourceIssue` the Related issues section ends with `noSourceStatement` (default
17
+ * {@link defaultNoSourceStatement}), after any `Refs` lines, instead of `- None`. Pure; the caller
18
+ * supplies the device and worktree facts. Throws when the fields leave a code fence open.
18
19
  */
19
20
  export declare function renderPullRequestBody(input: PullRequestInput, provenance: PullRequestProvenance, noSourceStatement?: string): string;
20
21
  /**
@@ -1,5 +1,6 @@
1
1
  import { basename } from 'node:path';
2
2
  import { formatReferenceKey } from "../gh-cli/closing-refs.mjs";
3
+ import { assertNoOpenFence } from "./pr-journal.mjs";
3
4
  function relatedLine(issue) {
4
5
  const verb = issue.relation === 'closes' ? 'Closes' : 'Refs';
5
6
  const [owner, repo] = issue.repository?.split('/') ?? [];
@@ -11,9 +12,10 @@ function defaultNoSourceStatement(reason) {
11
12
  }
12
13
  /**
13
14
  * The pull request body: the Summary, Impact, Related issues and Details sections followed by the
14
- * provenance lines. With `noSourceIssue` the Related issues section ends with `noSourceStatement`
15
- * (default {@link defaultNoSourceStatement}), after any `Refs` lines, instead of `- None`. Pure;
16
- * the caller supplies the device and worktree facts.
15
+ * provenance lines, collapsed in a Provenance disclosure because they serve audits, not reviewers.
16
+ * With `noSourceIssue` the Related issues section ends with `noSourceStatement` (default
17
+ * {@link defaultNoSourceStatement}), after any `Refs` lines, instead of `- None`. Pure; the caller
18
+ * supplies the device and worktree facts. Throws when the fields leave a code fence open.
17
19
  */
18
20
  export function renderPullRequestBody(input, provenance, noSourceStatement) {
19
21
  const related = input.relatedIssues.map(relatedLine);
@@ -21,7 +23,7 @@ export function renderPullRequestBody(input, provenance, noSourceStatement) {
21
23
  related.push(noSourceStatement ?? defaultNoSourceStatement(input.noSourceIssue.reason));
22
24
  if (!related.length)
23
25
  related.push('- None');
24
- return [
26
+ const fields = [
25
27
  '## Summary',
26
28
  '',
27
29
  input.summary,
@@ -37,12 +39,22 @@ export function renderPullRequestBody(input, provenance, noSourceStatement) {
37
39
  '## Details',
38
40
  '',
39
41
  input.details.join('\n\n'),
42
+ ].join('\n');
43
+ // An unclosed fence would turn the Provenance disclosure and its lines into visible code.
44
+ assertNoOpenFence(fields);
45
+ return [
46
+ fields,
47
+ '',
48
+ '<details>',
49
+ '<summary>Provenance</summary>',
40
50
  '',
41
51
  `Workspace setup: ${input.workspaceSetup}`,
42
52
  `Agent: ${provenance.agent} session ${provenance.sessionId}`,
43
53
  `Device: ${provenance.user}@${provenance.host.toLowerCase()}`,
44
54
  `Worktree: ${provenance.worktree}`,
45
55
  '',
56
+ '</details>',
57
+ '',
46
58
  ].join('\n');
47
59
  }
48
60
  const MARKER = '/worktrees/';
@@ -10,3 +10,5 @@ export declare function findShepherdJournal(body: string): string | undefined;
10
10
  * their own, and must not leave a code fence open: the journal would be hidden inside it.
11
11
  */
12
12
  export declare function preserveShepherdJournal(rendered: string, live: string): string;
13
+ /** Rejects text that ends inside an unclosed code fence: whatever follows would render as code. */
14
+ export declare function assertNoOpenFence(text: string): void;
@@ -80,7 +80,11 @@ export function preserveShepherdJournal(rendered, live) {
80
80
  const journal = findShepherdJournal(live);
81
81
  if (journal === undefined)
82
82
  return rendered;
83
- if (outsideFences(rendered.replaceAll('\r\n', '\n').split('\n')).open)
84
- throw new Error('the pull request fields leave a code fence open; close it');
83
+ assertNoOpenFence(rendered);
85
84
  return `${rendered.trimEnd()}\n\n${journal}\n`;
86
85
  }
86
+ /** Rejects text that ends inside an unclosed code fence: whatever follows would render as code. */
87
+ export function assertNoOpenFence(text) {
88
+ if (outsideFences(text.replaceAll('\r\n', '\n').split('\n')).open)
89
+ throw new Error('the pull request fields leave a code fence open; close it');
90
+ }
@@ -64,7 +64,8 @@ const FIELDS = {
64
64
  };
65
65
  const REQUIRED = ['title', 'summary', 'impact', 'relatedIssues', 'details', 'workspaceSetup'];
66
66
  const RENDERING = 'The server renders the body from the structured input (Summary, Impact, Related issues, ' +
67
- 'Details, then Workspace setup, Agent, Device and Worktree lines) and runs the checkout ' +
67
+ 'Details, then Workspace setup, Agent, Device and Worktree lines in a collapsed Provenance ' +
68
+ 'disclosure) and runs the checkout ' +
68
69
  'policy validatePullRequest export in a child process; the head branch is the ' +
69
70
  "worktree's current branch. Policy tools need a server launched inside a repository worktree. ";
70
71
  export const PR_TOOLS = [
@@ -88,4 +88,5 @@ export declare function loadPostgresParser(caller: string): Promise<{
88
88
  }>): Promise<import("no-mistakes").WithInvocationResult<import("no-mistakes").PostgresCompleteCatalog>>;
89
89
  generatePostgresCatalog(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").PostgresCatalogOptions>): Promise<import("no-mistakes").WithInvocationResult<import("no-mistakes").PostgresCatalog>>;
90
90
  analyzeTypeScriptModules(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").TypeScriptModulesOptions>): Promise<import("no-mistakes").WithInvocationResult<import("no-mistakes").TypeScriptModulesReport>>;
91
+ lockStatus(): Promise<import("no-mistakes").LockStatus>;
91
92
  }>;
@@ -362,12 +362,20 @@ rule) and `pullRequestDefaults`.
362
362
 
363
363
  <details joined by blank lines>
364
364
 
365
+ <details>
366
+ <summary>Provenance</summary>
367
+
365
368
  Workspace setup: <workspaceSetup>
366
369
  Agent: <derived agent | unknown>[ (caller-claimed ...)] session <sessionId>
367
370
  Device: <os user>@<lowercased hostname>
368
371
  Worktree: <path after "/worktrees/", "main" for the main worktree, else the directory name>
372
+
373
+ </details>
369
374
  ```
370
375
 
376
+ The provenance lines are collapsed because they serve audits, not reviewers; each still starts its
377
+ own line, so a policy can match them with line-anchored patterns.
378
+
371
379
  The head branch is the worktree's current branch (for `pr_validate` with `pr`, the live pull
372
380
  request's head, which may equal `base` for a fork); otherwise a detached HEAD, or a head equal to `base`, is rejected. The body must stay within GitHub's 65536 characters. `pr_create` sees no stack membership,
373
381
  so a consumer policy may reject any `base` other than the default branch; create stacked layers
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vouchington-tooling",
3
- "version": "0.85.3",
3
+ "version": "0.86.0",
4
4
  "description": "Vouchington CLI and extractable tooling libraries.",
5
5
  "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
6
6
  "bugs": {
@@ -536,11 +536,11 @@
536
536
  "@types/react": "19.3.0",
537
537
  "@types/react-dom": "19.3.0",
538
538
  "@types/spdx-expression-parse": "4.0.0",
539
- "@vouchington/postgres": "0.1.2",
540
- "@vouchington/worker-runtime": "0.2.1",
539
+ "@vouchington/postgres": "0.4.0",
540
+ "@vouchington/worker-runtime": "0.3.1",
541
541
  "glide-mq": "^0.20.0",
542
542
  "next": "16.4.3",
543
- "no-mistakes": "0.101.0",
543
+ "no-mistakes": "0.108.0",
544
544
  "pg": "8.23.1",
545
545
  "react": "19.3.1",
546
546
  "react-dom": "19.3.1",