vouchington-tooling 0.85.3 → 0.86.1
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/markdown/details-scope.d.mts +1 -1
- package/dist/markdown/details-scope.mjs +12 -2
- package/dist/markdown/index.d.mts +2 -0
- package/dist/markdown/index.mjs +1 -0
- package/dist/markdown/visible-content-types.d.mts +40 -0
- package/dist/markdown/visible-content-types.mjs +1 -0
- package/dist/markdown/visible-content.d.mts +3 -0
- package/dist/markdown/visible-content.mjs +114 -0
- package/dist/mcp-server/pr-body.d.mts +4 -3
- package/dist/mcp-server/pr-body.mjs +16 -4
- package/dist/mcp-server/pr-journal.d.mts +2 -0
- package/dist/mcp-server/pr-journal.mjs +6 -2
- package/dist/mcp-server/tools-pr.mjs +2 -1
- package/dist/sql-ast/no-mistakes-peer.d.mts +1 -0
- package/docs/mcp-server.md +8 -0
- package/package.json +4 -4
- package/scripts/__pycache__/run_bounded_process.cpython-314.pyc +0 -0
- package/skills/bounded-iteration/SKILL.md +7 -5
- package/skills/bounded-iteration/references/sweep-patterns.md +3 -0
- package/skills/glide-mq/SKILL.md +2 -1
- package/skills/manifest.json +5 -5
- package/skills/postgres-node-performance-tuning/SKILL.md +6 -0
- package/skills/postgres-node-performance-tuning/references/performance-patterns.md +22 -5
- package/skills/postgres-schema-design/SKILL.md +7 -0
- package/skills/postgres-schema-design/references/table-shapes.md +3 -1
|
@@ -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';
|
package/dist/markdown/index.mjs
CHANGED
|
@@ -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,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
|
|
16
|
-
*
|
|
17
|
-
*
|
|
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
|
|
15
|
-
*
|
|
16
|
-
*
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
}>;
|
package/docs/mcp-server.md
CHANGED
|
@@ -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.
|
|
3
|
+
"version": "0.86.1",
|
|
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.
|
|
540
|
-
"@vouchington/worker-runtime": "0.
|
|
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.
|
|
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",
|
|
Binary file
|
|
@@ -44,11 +44,13 @@ A run's cost is the rows it reads and the work it starts, not the memory it hold
|
|
|
44
44
|
continue with a plain keyset cursor, `(key, id) < ($1, $2)`. The page `LIMIT` plus a time window
|
|
45
45
|
or the keyset bound the read. A keyset alone does not bound rows scanned. When a filter can
|
|
46
46
|
reject long runs, such as a viewer's blocks or mutes, the time window is the scan bound where the
|
|
47
|
-
sort has one, and EXPLAIN at representative cardinality compares rows read with rows returned.
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
47
|
+
sort has one, and EXPLAIN at representative cardinality compares rows read with rows returned. The
|
|
48
|
+
simplest query comes first; anything more complex needs `EXPLAIN ANALYZE` plans beating it. For a
|
|
49
|
+
ranked list that is a join and `ORDER BY` on the stored score. No candidate pools: no capped or
|
|
50
|
+
`MATERIALIZED` CTE over the listed entity that is filtered or limited afterward, no window loops
|
|
51
|
+
or resume probes, no proof state in the cursor, and no runtime-config fields that exist only to
|
|
52
|
+
cap a read. A single walk with an inspected-row cap is fine, and may return a short or empty page
|
|
53
|
+
with a continuation cursor and `has_next_page` true. Small viewer-scoped sets (the viewer's follows, mutes, blocks and
|
|
52
54
|
memberships) may be subqueries or semi-joins, because write limits bound them. Measure a
|
|
53
55
|
list-read change against the plain single walk, not only against the base branch. See
|
|
54
56
|
[`MATERIALIZED` CTEs](../postgres-node-performance-tuning/references/performance-patterns.md).
|
|
@@ -342,6 +342,9 @@ CROSS JOIN LATERAL (
|
|
|
342
342
|
) due;
|
|
343
343
|
```
|
|
344
344
|
|
|
345
|
+
This is a complex shape: keep it only with `EXPLAIN ANALYZE` plans showing it beats the plain
|
|
346
|
+
query.
|
|
347
|
+
|
|
345
348
|
The loose scan beats a small thresholds table here because the intervals are chosen per row and
|
|
346
349
|
there is no second source of truth to drift. If the intervals are a fixed, reviewed set, a
|
|
347
350
|
thresholds table is just as bounded. Either way the bucket count must itself be bounded, for
|
package/skills/glide-mq/SKILL.md
CHANGED
|
@@ -44,7 +44,8 @@ option `concurrency`, `lockDuration`, and `job.moveToDelayed(timestamp)`. Read
|
|
|
44
44
|
|
|
45
45
|
Dispatchers, paged fan-out, and job-id deduplication follow
|
|
46
46
|
[bounded iteration](../bounded-iteration/SKILL.md). A lease for work that spans an external call
|
|
47
|
-
replaces holding a PostgreSQL transaction
|
|
47
|
+
replaces holding a PostgreSQL transaction open across it, and PostgreSQL advisory locks are never
|
|
48
|
+
used; see
|
|
48
49
|
[performance patterns](../postgres-node-performance-tuning/references/performance-patterns.md).
|
|
49
50
|
|
|
50
51
|
Consumer policy owns queue names, lane keys, caps and their configuration source, the lease helper,
|
package/skills/manifest.json
CHANGED
|
@@ -30,7 +30,7 @@
|
|
|
30
30
|
{
|
|
31
31
|
"name": "bounded-iteration",
|
|
32
32
|
"plugin": "vouchington-database",
|
|
33
|
-
"pluginVersion": "0.
|
|
33
|
+
"pluginVersion": "0.11.0",
|
|
34
34
|
"path": "bounded-iteration/SKILL.md"
|
|
35
35
|
},
|
|
36
36
|
{
|
|
@@ -81,7 +81,7 @@
|
|
|
81
81
|
{
|
|
82
82
|
"name": "glide-mq",
|
|
83
83
|
"plugin": "vouchington-database",
|
|
84
|
-
"pluginVersion": "0.
|
|
84
|
+
"pluginVersion": "0.11.0",
|
|
85
85
|
"path": "glide-mq/SKILL.md"
|
|
86
86
|
},
|
|
87
87
|
{
|
|
@@ -127,19 +127,19 @@
|
|
|
127
127
|
{
|
|
128
128
|
"name": "postgres-node-performance-tuning",
|
|
129
129
|
"plugin": "vouchington-database",
|
|
130
|
-
"pluginVersion": "0.
|
|
130
|
+
"pluginVersion": "0.11.0",
|
|
131
131
|
"path": "postgres-node-performance-tuning/SKILL.md"
|
|
132
132
|
},
|
|
133
133
|
{
|
|
134
134
|
"name": "postgres-partitioning-uuid-v7",
|
|
135
135
|
"plugin": "vouchington-database",
|
|
136
|
-
"pluginVersion": "0.
|
|
136
|
+
"pluginVersion": "0.11.0",
|
|
137
137
|
"path": "postgres-partitioning-uuid-v7/SKILL.md"
|
|
138
138
|
},
|
|
139
139
|
{
|
|
140
140
|
"name": "postgres-schema-design",
|
|
141
141
|
"plugin": "vouchington-database",
|
|
142
|
-
"pluginVersion": "0.
|
|
142
|
+
"pluginVersion": "0.11.0",
|
|
143
143
|
"path": "postgres-schema-design/SKILL.md"
|
|
144
144
|
},
|
|
145
145
|
{
|
|
@@ -11,6 +11,12 @@ Local policy overrides these defaults; do not reload an already-read adapter or
|
|
|
11
11
|
|
|
12
12
|
Measure the query plan and the workload shape before changing code.
|
|
13
13
|
|
|
14
|
+
Owner's principle: "the basic premise is to use the simplest query, and making it more complex
|
|
15
|
+
requires explain analyze plans". Start with filters in `WHERE`, keyed `EXISTS`, joins or
|
|
16
|
+
subqueries, `ORDER BY`, and `LIMIT`. A complex shape stays only with `EXPLAIN ANALYZE` plans showing
|
|
17
|
+
it beats that simple query, not merely the previous version; see
|
|
18
|
+
[simplest query first](references/performance-patterns.md#simplest-query-first).
|
|
19
|
+
|
|
14
20
|
- Select only the required columns.
|
|
15
21
|
- Bound each result set. Paginate or stream a large read. A stream bounds memory, not work: cap
|
|
16
22
|
the rows per run as in [bounded iteration](../bounded-iteration/SKILL.md).
|
|
@@ -3,8 +3,8 @@
|
|
|
3
3
|
Use pools and release checked-out clients in `finally`, especially for cursors, streams, and COPY.
|
|
4
4
|
Route ordinary reads to a replica when its lag is acceptable; route read-after-write, locking, and
|
|
5
5
|
transaction-consistent reads to the writer. Do not hold a client across unrelated application work.
|
|
6
|
-
Never hold a transaction
|
|
7
|
-
in a shared store instead, with a TTL, renewal, and compare-and-delete release. Stop work when
|
|
6
|
+
Never use advisory locks, and never hold a transaction or connection across an external call; take
|
|
7
|
+
a token lease in a shared store instead, with a TTL, renewal, and compare-and-delete release. Stop work when
|
|
8
8
|
renewal fails, and guard any write a stale owner could make with the token.
|
|
9
9
|
|
|
10
10
|
For large reads, use keyset pagination, cursors, or streams with cancellation and bounded batches.
|
|
@@ -21,6 +21,19 @@ data, but it does not replace suitable local indexes or predicates that permit p
|
|
|
21
21
|
|
|
22
22
|
## Query shapes
|
|
23
23
|
|
|
24
|
+
### Simplest query first
|
|
25
|
+
|
|
26
|
+
Owner's principle: "hot/best should just be a JOIN and an ORDER BY". A ranked sort joins the
|
|
27
|
+
entity to its stored score and orders by it. Filters go in `WHERE`; membership is a keyed `EXISTS`,
|
|
28
|
+
join, or subquery; then `ORDER BY` and `LIMIT`.
|
|
29
|
+
|
|
30
|
+
These need `EXPLAIN ANALYZE` plans, at representative cardinality, showing they beat the simple
|
|
31
|
+
query for the same result, not merely the previous version on the base branch: `MATERIALIZED` or
|
|
32
|
+
capped candidate CTEs, `UNION`, `GROUP BY` or `DISTINCT` dedupe, `LATERAL` joins and planner
|
|
33
|
+
fences, cohort or window ranking, and multi-stage cap-filter-rank pipelines. Never build a
|
|
34
|
+
candidate pool. A walk that stops at an inspected-row cap and returns a short or empty page with a
|
|
35
|
+
continuation cursor is fine.
|
|
36
|
+
|
|
24
37
|
Test existence with `EXISTS`, not `COUNT(*) > 0`. Use correlated `NOT EXISTS` rather than
|
|
25
38
|
`NOT IN (SELECT ...)`, whose NULL behavior can silently exclude expected rows. Filter and order
|
|
26
39
|
UUIDv7 rows by `id`, not generated `created_at`, so the key's index supports the query.
|
|
@@ -32,7 +45,8 @@ Use keyset pagination, never `OFFSET`. An optimizer fence is a `MATERIALIZED` CT
|
|
|
32
45
|
The outer query still reads CTE rows on demand and can stop at its `LIMIT`, but when its filters
|
|
33
46
|
reject most CTE rows, or it sorts, aggregates or hash-joins them, it reads every row up to the CTE's own
|
|
34
47
|
`LIMIT`. Use a `MATERIALIZED` CTE only when it holds the final `LIMIT`, or for a small
|
|
35
|
-
viewer-scoped set
|
|
48
|
+
viewer-scoped set, and only with plans showing it beats the plain query. Never use it as a
|
|
49
|
+
candidate pool before the page `LIMIT`. Constrain a partitioned table's partition key, or document the reason for a
|
|
36
50
|
cross-partition query. Choose the partition key from dominant access patterns; a hot reader
|
|
37
51
|
of `RANGE (id)` needs an id or time bound.
|
|
38
52
|
|
|
@@ -98,7 +112,8 @@ count over its output. A restriction on a grouping column can still be pushed be
|
|
|
98
112
|
so let the plan decide. Confirm from the
|
|
99
113
|
plan (large `Actual Rows` and `Actual Loops` inside the view's nodes), then choose the ids from the
|
|
100
114
|
base tables first and read the view by its key, as a correlated `LATERAL` lookup so the page
|
|
101
|
-
restriction can reach inside the view.
|
|
115
|
+
restriction can reach inside the view. Reach for this only after the plan shows the simple
|
|
116
|
+
query builds the whole view, and keep it only if its plan beats the simple query. This works for an aggregate or `GROUP BY` view whose key is
|
|
102
117
|
a grouping column; a `LIMIT` in the view blocks pushdown of any qual, so rewrite that view's query
|
|
103
118
|
against the base tables instead. A plain join to the page is a join clause, not a restriction
|
|
104
119
|
inside the view, so the planner can still build the whole aggregate first.
|
|
@@ -148,7 +163,9 @@ Overlap independent cache and PostgreSQL reads with `Promise.all`, such as a rat
|
|
|
148
163
|
alongside the user fetch. Serialize only true dependencies, where one result feeds the next call. Suppress the
|
|
149
164
|
sequential-await lint only when each step consumes the previous step's result; a shared
|
|
150
165
|
transaction client or lock ordering is not a data dependency. A lock that must be taken first
|
|
151
|
-
stays a separate, earlier statement; never reorder or parallelize it.
|
|
166
|
+
stays a separate, earlier statement; never reorder or parallelize it. Do not keep a lock only
|
|
167
|
+
because it exists: one that fails the lock rule in
|
|
168
|
+
[schema design](../../postgres-schema-design/SKILL.md) is deleted. Audit every added suppression.
|
|
152
169
|
|
|
153
170
|
Correctness comes before round trips. Before folding a statement away, state the guarantee it
|
|
154
171
|
gave (what it locked, which snapshot it read) and reject the fold if that weakens. An `EXISTS`
|
|
@@ -14,6 +14,13 @@ Local policy overrides these portable conventions.
|
|
|
14
14
|
- Split differing shapes, share identical values, and keep history documents as JSON.
|
|
15
15
|
- Use canonical [table shapes](references/table-shapes.md) for revisions, changes, work, and cursors.
|
|
16
16
|
- Default to finite retention for everything except user content; see [table shapes](references/table-shapes.md#retention).
|
|
17
|
+
- No unnecessary locks. Owner's words: "do we have a rule? no unnecessary locks", "seems like we
|
|
18
|
+
have way too many locks for no reason", "keep things simple". Lock (`FOR UPDATE`) only when a
|
|
19
|
+
concurrent write would corrupt the rows this transaction writes. Never lock a read set or a
|
|
20
|
+
parent row, and never use advisory locks. Caps and "don't remove the last X" guards are best
|
|
21
|
+
effort: count up to the cap (`LIMIT cap+1`), then write. Never add counter or projection tables,
|
|
22
|
+
slot tables, claim tables, or constraints that exist only to make a cap exact. Remove a lock by
|
|
23
|
+
deleting it, not by swapping in another serializer.
|
|
17
24
|
- Reuse parameterized trigger functions instead of copying bodies.
|
|
18
25
|
- Comment every table, column, and view; document reviewed exceptions explicitly.
|
|
19
26
|
|
|
@@ -29,7 +29,9 @@ Default to a queue job whose job id is the durable row id, enqueued after commit
|
|
|
29
29
|
sweep that re-enqueues rows with no recorded outcome. The queue already supplies attempts,
|
|
30
30
|
backoff, locking, stall recovery and unique ids. A lease or outbox work-item table needs a stated
|
|
31
31
|
reason: legal or payment records, old values that vanish at commit, or an outcome that must
|
|
32
|
-
commit with domain rows.
|
|
32
|
+
commit with domain rows. Making a cap exact is never a reason: no counter, slot, or claim table
|
|
33
|
+
for a cap; count up to the cap and write, as in the lock rule in
|
|
34
|
+
[schema design](../SKILL.md).
|
|
33
35
|
|
|
34
36
|
When a table is justified, fence with one compare-and-set on the outcome or a generation
|
|
35
37
|
(`WHERE completed_at IS NULL` / `AND generation = $n`) instead of a full set of lease columns.
|