Merge pull request 'Record references link to what they cite, by title' (#223) from dev into main
CI & Build / Python lint (push) Successful in 2s
CI & Build / Plugin hooks (push) Successful in 12s
CI & Build / TypeScript typecheck (push) Successful in 34s
CI & Build / Python tests (push) Successful in 1m50s
CI & Build / integration (push) Successful in 1m55s
CI & Build / Build & push image (push) Successful in 17s

This commit was merged in pull request #223.
This commit is contained in:
2026-11-22 17:58:22 -05:00
24 changed files with 907 additions and 48 deletions
+39
View File
@@ -147,6 +147,45 @@
text-decoration: none; text-decoration: none;
} }
/* A record reference — `#4286`, `milestone 639`, `rule 34`. Reads as a link in
running text rather than a chip: a work log cites a dozen of them, and a row
of pills would drown the sentence they sit in. */
.record-ref {
color: var(--fs-wikilink);
text-decoration: underline;
text-decoration-color: color-mix(in srgb, var(--fs-wikilink) 40%, transparent);
text-underline-offset: 0.15em;
font-variant-numeric: tabular-nums;
border-radius: var(--fs-radius-sm);
cursor: pointer;
}
.record-ref:hover {
text-decoration-color: currentColor;
}
/* Drawn with its title: the title reads as the link, the number after it is
the citation, quieter and never split across lines. */
.record-ref__id {
color: var(--fs-text-secondary);
font-size: 0.85em;
white-space: nowrap;
}
.record-ref:focus-visible {
outline: none;
box-shadow: var(--fs-focus-ring);
}
/* One the reader cannot open: missing, trashed or not shared. Still legible —
the number is part of the sentence — but plainly not a way through. */
.record-ref--missing {
color: var(--fs-text-tertiary-fg);
text-decoration-style: dashed;
text-decoration-color: var(--fs-text-tertiary);
cursor: default;
}
/* Task list */ /* Task list */
.prose ul[data-type="taskList"] { .prose ul[data-type="taskList"] {
list-style: none; list-style: none;
+2 -1
View File
@@ -2,6 +2,7 @@
import { ref, onMounted } from "vue"; import { ref, onMounted } from "vue";
import { apiGet, apiPost, apiPatch, apiDelete } from "@/api/client"; import { apiGet, apiPost, apiPatch, apiDelete } from "@/api/client";
import { renderMarkdown } from "@/utils/markdown"; import { renderMarkdown } from "@/utils/markdown";
import { vRecordRefs } from "@/directives/recordRefs";
import type { TaskLog } from "@/types/task"; import type { TaskLog } from "@/types/task";
import { fmtStamp } from "@/utils/dateFormat"; import { fmtStamp } from "@/utils/dateFormat";
@@ -131,7 +132,7 @@ onMounted(loadLogs);
<button class="btn-text" aria-label="Delete log entry" @click="deleteLog(log)">&times;</button> <button class="btn-text" aria-label="Delete log entry" @click="deleteLog(log)">&times;</button>
</div> </div>
</div> </div>
<div class="log-content prose" v-html="renderMarkdown(log.content)"></div> <div class="log-content prose" v-html="renderMarkdown(log.content)" v-record-refs></div>
</template> </template>
</div> </div>
+2 -1
View File
@@ -51,7 +51,8 @@ export function useAutocomplete(
// Must be start of line or preceded by whitespace // Must be start of line or preceded by whitespace
if (i === 0 || /\s/.test(text[i - 1])) { if (i === 0 || /\s/.test(text[i - 1])) {
const query = text.slice(i + 1, cursor); const query = text.slice(i + 1, cursor);
if (/^[\w/]*$/.test(query)) { // Digits alone are a record reference being typed (`#4286`), not a tag.
if (/^[\w/]*$/.test(query) && !/^\d+$/.test(query)) {
acTriggerStart = i; acTriggerStart = i;
acType = "tag"; acType = "tag";
debouncedSearch(query); debouncedSearch(query);
+199
View File
@@ -0,0 +1,199 @@
import type { ObjectDirective } from "vue";
import { apiPost } from "@/api/client";
import router from "@/router";
import { recordHref } from "@/utils/recordHref";
import type { RefSpace } from "@/utils/recordRefs";
/** v-record-refs — makes the `a.record-ref` links in a v-html body real.
*
* Put it on the element that holds rendered markdown:
* <div class="prose" v-html="renderMarkdown(body)" v-record-refs />
*
* After each render it asks the server, once for the whole body, what every
* referenced id is. Each link then gets the route its kind opens at (a `#N`
* may be a task, lesson or snippet), the record's title drawn before its
* number — "Fix the cache key #3127" — so a reader knows what is cited
* without hovering, its kind, full title and status as a tooltip, and a
* "leads nowhere" style when the reader cannot open it: missing, trashed and
* not-shared-with-you look the same, on purpose, and keep the bare number.
* The stored text stays `#N`; the title is read at render, so an edited
* title shows everywhere it is cited.
* A plain click navigates in the app; a modified click (new tab) keeps the
* browser's own behaviour.
*/
interface NoteInfo { id: number; title: string; is_task: boolean; note_type: string; status: string | null; task_kind: string | null }
interface MilestoneInfo { id: number; title: string; project_id: number | null; status: string }
interface RuleInfo { id: number; title: string; kind: string }
type Resolved = { notes: Record<string, NoteInfo>; milestones: Record<string, MilestoneInfo>; rules: Record<string, RuleInfo> };
// `title` is drawn in the link; `label` (kind · title (status)) is its tooltip.
type Info = { href: string; title: string; label: string } | null;
// A short-lived cache: the same body re-renders on every keystroke in a
// preview, and a page of work logs cites the same few records again and again.
const CACHE_MS = 60_000;
const cache = new Map<string, { at: number; info: Info }>();
const TASK_KIND_LABEL: Record<string, string> = { issue: "Issue", spike: "Spike" };
function noteInfo(n: NoteInfo): Info {
let kind = "Note";
if (n.is_task) kind = TASK_KIND_LABEL[n.task_kind ?? ""] ?? "Task";
else if (n.note_type === "lesson") kind = "Lesson";
else if (n.note_type === "snippet") kind = "Snippet";
const state = n.is_task && n.status ? ` (${n.status.replace(/_/g, " ")})` : "";
const title = n.title || "Untitled";
return { href: recordHref(n), title, label: `${kind} · ${title}${state}` };
}
function milestoneInfo(m: MilestoneInfo): Info {
if (m.project_id == null) return null;
const title = m.title || "Untitled";
return {
href: `/projects/${m.project_id}?milestone=${m.id}`,
title,
label: `Milestone · ${title}${m.status === "done" ? " (done)" : ""}`,
};
}
function ruleInfo(r: RuleInfo): Info {
const kind = r.kind === "preference" ? "Preference" : "Rule";
const title = r.title || "Untitled";
return { href: `/rules?rule=${r.id}`, title, label: `${kind} · ${title}` };
}
// Titles here are often whole sentences; in running text a reference names its
// record in a few words and the tooltip carries the rest.
const MAX_TITLE = 60;
function shorten(title: string): string {
if (title.length <= MAX_TITLE) return title;
const cut = title.slice(0, MAX_TITLE);
const space = cut.lastIndexOf(" ");
return (space > MAX_TITLE / 2 ? cut.slice(0, space) : cut).replace(/[\s,.;:—–-]+$/, "") + "…";
}
const BLOCK = "p, li, td, th, blockquote, h1, h2, h3, h4, h5, h6";
/** Whether the sentence around this link already names the record — a batch
* writes `#9 "Step two"`, and a paragraph citing one record twice names it
* the first time. A short title is drawn regardless: three letters turn up
* in prose by chance. */
function alreadyNamed(a: HTMLAnchorElement, shown: string, title: string): boolean {
if (title.length < 8) return false;
const text = (a.closest(BLOCK) ?? a.parentElement)?.textContent?.toLowerCase() ?? "";
return text.includes(title.toLowerCase()) || text.includes(shown.toLowerCase());
}
/** Draw the record's title in the link, its number after it, muted. Set as
* text, never as markup: a title is whatever its author typed. */
function showTitle(a: HTMLAnchorElement, title: string): boolean {
const shown = shorten(title);
if (alreadyNamed(a, shown, title)) return false;
const name = document.createElement("span");
name.className = "record-ref__title";
name.textContent = shown;
const ref = document.createElement("span");
ref.className = "record-ref__id";
ref.textContent = a.textContent ?? "";
a.replaceChildren(name, " ", ref);
return true;
}
function refKey(space: RefSpace, id: number): string {
return `${space}:${id}`;
}
/** What each of these references is, from the cache or one server call. */
export async function resolveRecordRefs(wanted: { space: RefSpace; id: number }[]): Promise<Map<string, Info>> {
const now = Date.now();
const out = new Map<string, Info>();
const ask: Record<RefSpace, number[]> = { notes: [], milestones: [], rules: [] };
for (const w of wanted) {
const k = refKey(w.space, w.id);
if (out.has(k)) continue;
const hit = cache.get(k);
if (hit && now - hit.at < CACHE_MS) out.set(k, hit.info);
else if (!ask[w.space].includes(w.id)) ask[w.space].push(w.id);
}
if (ask.notes.length + ask.milestones.length + ask.rules.length === 0) return out;
const res = await apiPost<Resolved>("/api/notes/resolve-refs", ask);
const store = (space: RefSpace, id: number, info: Info) => {
cache.set(refKey(space, id), { at: now, info });
out.set(refKey(space, id), info);
};
for (const id of ask.notes) store("notes", id, res.notes[id] ? noteInfo(res.notes[id]) : null);
for (const id of ask.milestones) store("milestones", id, res.milestones[id] ? milestoneInfo(res.milestones[id]) : null);
for (const id of ask.rules) store("rules", id, res.rules[id] ? ruleInfo(res.rules[id]) : null);
return out;
}
function unresolvedLinks(el: HTMLElement): HTMLAnchorElement[] {
return Array.from(el.querySelectorAll<HTMLAnchorElement>("a.record-ref:not([data-ref-state])"));
}
async function decorate(el: HTMLElement) {
const links = unresolvedLinks(el);
if (!links.length) return;
const wanted = links.map((a) => ({ space: a.dataset.refSpace as RefSpace, id: Number(a.dataset.refId) }));
let resolved: Map<string, Info>;
try {
resolved = await resolveRecordRefs(wanted);
} catch {
// The links keep their provisional routes, which open the right view for
// notes, rules and milestones alike; only the titles are missing.
return;
}
for (const a of links) {
if (!a.isConnected) continue;
const info = resolved.get(refKey(a.dataset.refSpace as RefSpace, Number(a.dataset.refId)));
if (info === undefined) continue;
if (info === null) {
a.dataset.refState = "missing";
a.classList.add("record-ref--missing");
a.removeAttribute("href");
a.setAttribute("aria-disabled", "true");
a.title = `${a.textContent} — no record you can open`;
continue;
}
a.dataset.refState = "ok";
a.href = info.href;
a.title = info.label;
const bare = a.textContent;
// Drawn with its title, the link's own text is its accessible name; a bare
// number needs the label spoken for it.
if (!showTitle(a, info.title)) a.setAttribute("aria-label", `${bare}: ${info.label}`);
}
}
const clickHandlers = new WeakMap<HTMLElement, (e: MouseEvent) => void>();
function onClick(e: MouseEvent) {
const a = (e.target as HTMLElement).closest("a.record-ref") as HTMLAnchorElement | null;
if (!a) return;
if (a.dataset.refState === "missing") {
e.preventDefault();
return;
}
if (e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
const href = a.getAttribute("href");
if (!href) return;
e.preventDefault();
router.push(href);
}
export const vRecordRefs: ObjectDirective<HTMLElement> = {
mounted(el) {
clickHandlers.set(el, onClick);
el.addEventListener("click", onClick);
void decorate(el);
},
updated(el) {
void decorate(el);
},
beforeUnmount(el) {
const h = clickHandlers.get(el);
if (h) el.removeEventListener("click", h);
clickHandlers.delete(el);
},
};
+3 -1
View File
@@ -2,7 +2,9 @@ import { Extension } from "@tiptap/core";
import { Plugin, PluginKey } from "@tiptap/pm/state"; import { Plugin, PluginKey } from "@tiptap/pm/state";
import { Decoration, DecorationSet } from "@tiptap/pm/view"; import { Decoration, DecorationSet } from "@tiptap/pm/view";
const TAG_RE = /(?<=\s|^)#([\w]+(?:\/[\w]+)*)/g; // Digits alone (`#4286`) are a record reference, not a tag, and are left plain
// here; the rendered view links them (utils/recordRefs.ts).
const TAG_RE = /(?<=\s|^)#(?!\d+(?![\w/-]))([\w]+(?:\/[\w]+)*)/g;
export const TagDecoration = Extension.create({ export const TagDecoration = Extension.create({
name: "tagDecoration", name: "tagDecoration",
+20
View File
@@ -123,6 +123,26 @@ const router = createRouter({
name: "project-view", name: "project-view",
component: () => import("@/views/ProjectView.vue"), component: () => import("@/views/ProjectView.vue"),
}, },
{
// Where a `milestone N` reference leads. A milestone is shown on its
// project's board, so this only looks up which project and goes there.
path: "/milestones/:id",
name: "milestone",
component: () => import("@/views/ProjectListView.vue"),
beforeEnter: async (to) => {
const id = Number(to.params.id);
const { resolveRecordRefs } = await import("@/directives/recordRefs");
try {
const found = (await resolveRecordRefs([{ space: "milestones", id }])).get(`milestones:${id}`);
if (found) return found.href;
} catch {
// Fall through to the projects list with the notice below.
}
const { useToastStore } = await import("@/stores/toast");
useToastStore().show(`No milestone ${id} you can open`, "warning");
return { name: "projects" };
},
},
{ {
path: "/rules", path: "/rules",
name: "rules", name: "rules",
+7 -4
View File
@@ -1,6 +1,7 @@
import { marked, type RendererThis, type Tokens } from "marked"; import { marked, type RendererThis, type Tokens } from "marked";
import DOMPurify from "dompurify"; import DOMPurify from "dompurify";
import { linkifyTags, linkifyWikilinks } from "@/utils/tags"; import { linkifyTags, linkifyWikilinks } from "@/utils/tags";
import { linkifyRecordRefs } from "@/utils/recordRefs";
function decodeEntities(text: string): string { function decodeEntities(text: string): string {
const textarea = document.createElement("textarea"); const textarea = document.createElement("textarea");
@@ -20,9 +21,11 @@ export function slugify(text: string): string {
export function stripFirstLineTags(text: string): string { export function stripFirstLineTags(text: string): string {
const match = text.match(/^[ \t]*((?:(?<!\w)#[\w]+(?:\/[\w]+)*[ \t]*)+)\n?/); const match = text.match(/^[ \t]*((?:(?<!\w)#[\w]+(?:\/[\w]+)*[ \t]*)+)\n?/);
if (!match) return text; if (!match) return text;
// Verify every #-token is a tag, not a heading (headings have "# " with space) // Verify every #-token is a tag, not a heading (headings have "# " with
// space) and not a record reference: a first line of "#4286 #4290" cites two
// records and stays in the body.
const tokens = match[1].trim().split(/\s+/); const tokens = match[1].trim().split(/\s+/);
const allTags = tokens.every((t) => /^#[\w]+(?:\/[\w]+)*$/.test(t)); const allTags = tokens.every((t) => /^#[\w]+(?:\/[\w]+)*$/.test(t) && !/^#\d+$/.test(t));
if (!allTags) return text; if (!allTags) return text;
return text.slice(match[0].length); return text.slice(match[0].length);
} }
@@ -38,7 +41,7 @@ const headingRenderer = {
marked.use({ renderer: headingRenderer }); marked.use({ renderer: headingRenderer });
const PURIFY_OPTS_FULL = { const PURIFY_OPTS_FULL = {
ADD_ATTR: ["data-tag", "data-title", "data-task-index"], ADD_ATTR: ["data-tag", "data-title", "data-task-index", "data-ref-space", "data-ref-id"],
FORCE_BODY: true, FORCE_BODY: true,
}; };
@@ -64,7 +67,7 @@ export function renderMarkdown(text: string, { interactiveCheckboxes = false } =
} }
const withTags = linkifyTags(html); const withTags = linkifyTags(html);
const withLinks = linkifyWikilinks(withTags); const withLinks = linkifyRecordRefs(linkifyWikilinks(withTags));
const sanitized = DOMPurify.sanitize(withLinks, PURIFY_OPTS_FULL); const sanitized = DOMPurify.sanitize(withLinks, PURIFY_OPTS_FULL);
// marked escapes ' to &#39; — replace after sanitization to ensure clean rendering // marked escapes ' to &#39; — replace after sanitization to ensure clean rendering
return sanitized.replace(/&#39;/g, "'"); return sanitized.replace(/&#39;/g, "'");
+104
View File
@@ -0,0 +1,104 @@
/** Record references in rendered prose: `#N`, `milestone N`, `rule N`.
*
* Three id spaces, three forms:
* `#N` a note, task, lesson or snippet (one sequence, the notes table)
* `milestone N` a milestone — the form a batch create writes for `{{ref:milestone}}`
* `rule N` a rule; `preference N` too, since a preference is a rule
* A `#N` after a word that names another numbering ("PR #198", "rule #34",
* "step #3") is not a note, and stays plain text.
*
* The backend reads references with the same patterns and the same word list
* (src/grimoire/services/record_refs.py: REF_RE, PROSE_REF_RE, _OTHER_SPACE),
* so a backlink, a graph edge and a rendered link agree about what a body
* cites. tests/test_record_ref_links.py fails when the two differ.
*
* linkifyRecordRefs only marks the references up. What each one IS — its
* route, its title, whether the reader can open it — is filled in after render
* by the v-record-refs directive (directives/recordRefs.ts), which asks the
* server once per rendered body.
*/
export const NOTE_REF_RE = /(?<![\w&#/])#(\d+)\b/g;
export const PROSE_REF_RE = /(?<![\w/])\b(milestone|rule|preference)\s+#?(\d+)\b/gi;
export const OTHER_SPACE: readonly string[] = [
"pr", "prs", "pull", "pulls", "request", "requests", "mr", "mrs",
"run", "runs", "ci", "build", "builds", "job", "jobs", "pipeline",
"action", "actions", "commit", "github", "gitlab", "gitea", "gh",
"rule", "rules", "preference", "preferences", "milestone", "milestones",
"system", "systems", "project", "projects", "log", "logs", "topic",
"topics", "rulebook", "rulebooks", "step", "steps", "rank", "line",
"lines", "page", "item", "option", "version", "port",
];
const OTHER_SPACE_SET = new Set(OTHER_SPACE);
const PREV_WORD_RE = /([A-Za-z]+)[\s"'(\[*_:]*$/;
export type RefSpace = "notes" | "milestones" | "rules";
export interface RefMatch {
start: number;
end: number;
space: RefSpace;
id: number;
}
function prevWord(before: string): string {
const m = PREV_WORD_RE.exec(before);
return m ? m[1].toLowerCase() : "";
}
/** Every reference in a run of plain text, in order, never overlapping.
* `context` is the text that came before this run, for the word in front of
* a `#N` that starts the run. */
export function findRecordRefs(text: string, context = ""): RefMatch[] {
const found: RefMatch[] = [];
for (const m of text.matchAll(PROSE_REF_RE)) {
const space: RefSpace = m[1].toLowerCase() === "milestone" ? "milestones" : "rules";
found.push({ start: m.index!, end: m.index! + m[0].length, space, id: Number(m[2]) });
}
for (const m of text.matchAll(NOTE_REF_RE)) {
const start = m.index!;
const end = start + m[0].length;
if (found.some((f) => start < f.end && end > f.start)) continue;
if (OTHER_SPACE_SET.has(prevWord(context + text.slice(0, start)))) continue;
found.push({ start, end, space: "notes", id: Number(m[1]) });
}
return found.sort((a, b) => a.start - b.start);
}
/** Where a reference opens before the server has said what it is. A note id
* may turn out to be a task, lesson or snippet; the directive corrects it. */
export function provisionalHref(space: RefSpace, id: number): string {
if (space === "milestones") return `/milestones/${id}`;
if (space === "rules") return `/rules?rule=${id}`;
return `/notes/${id}`;
}
// Markup a reference is never drawn inside: an existing link (a wikilink, a
// markdown link, a tag chip), code, and the tags themselves.
const SKIP_RE = /(<a\b[\s\S]*?<\/a>|<code[\s\S]*?<\/code>|<pre[\s\S]*?<\/pre>|<[^>]+>)/gi;
/** Wrap each record reference in rendered HTML in an `a.record-ref`. */
export function linkifyRecordRefs(html: string): string {
const parts = html.split(SKIP_RE);
let context = "";
return parts
.map((part, i) => {
// Odd indices are markup the split kept; text between them is even.
if (i % 2 === 1) return part;
const refs = findRecordRefs(part, context);
context = (context + part).slice(-80);
if (!refs.length) return part;
let out = "";
let at = 0;
for (const r of refs) {
out += part.slice(at, r.start);
const label = part.slice(r.start, r.end);
out += `<a class="record-ref" data-ref-space="${r.space}" data-ref-id="${r.id}" href="${provisionalHref(r.space, r.id)}">${label}</a>`;
at = r.end;
}
return out + part.slice(at);
})
.join("");
}
+5 -1
View File
@@ -1,5 +1,9 @@
const CODE_FENCE_RE = /```[\s\S]*?```|`[^`\n]+`/g; const CODE_FENCE_RE = /```[\s\S]*?```|`[^`\n]+`/g;
const TAG_RE = /(?<!\w)(?<!&)#([\w][\w-]*(?:\/[\w][\w-]*)*)/g; // A `#` token made only of digits is a record reference (`#3127` names a note,
// task, lesson or snippet; utils/recordRefs.ts links it), never a tag. Digits
// followed by more of a tag (`#2fa`, `#123-notes`) is still a tag. The backend's
// src/grimoire/utils/tags.py holds the same pattern.
export const TAG_RE = /(?<!\w)(?<!&)#(?!\d+(?![\w/-]))([\w][\w-]*(?:\/[\w][\w-]*)*)/g;
function escapeHtmlAttr(s: string): string { function escapeHtmlAttr(s: string): string {
return s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;"); return s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+11 -7
View File
@@ -8,6 +8,7 @@ import { drag } from "d3-drag";
import { select } from "d3-selection"; import { select } from "d3-selection";
import { apiGet } from "@/api/client"; import { apiGet } from "@/api/client";
import { renderMarkdown } from "@/utils/markdown"; import { renderMarkdown } from "@/utils/markdown";
import { vRecordRefs } from "@/directives/recordRefs";
const router = useRouter(); const router = useRouter();
@@ -26,7 +27,8 @@ interface GraphNode extends SimulationNodeDatum {
interface GraphEdge { interface GraphEdge {
source: number | string | GraphNode; source: number | string | GraphNode;
target: number | string | GraphNode; target: number | string | GraphNode;
type: "wikilink" | "tag"; /** wikilink: `[[title]]`; reference: a `#N` citation; tag: a shared tag. */
type: "wikilink" | "reference" | "tag";
} }
interface Project { interface Project {
@@ -237,12 +239,14 @@ function initGraph() {
.append("line") .append("line")
.attr("class", "graph-edge") .attr("class", "graph-edge")
.attr("stroke", (d: any) => .attr("stroke", (d: any) =>
d.type === "wikilink" ? "var(--fs-accent)" : "var(--fs-text-tertiary)" d.type === "tag" ? "var(--fs-text-tertiary)" : "var(--fs-accent)"
) )
.attr("stroke-opacity", (d: any) => (d.type === "wikilink" ? 0.5 : 0.4)) .attr("stroke-opacity", (d: any) => (d.type === "tag" ? 0.4 : 0.5))
.attr("stroke-dasharray", null) // A citation is a looser link than a wikilink: same colour and direction,
.attr("stroke-width", (d: any) => (d.type === "wikilink" ? 1.5 : 1)) // drawn dashed so the two read apart.
.attr("marker-end", (d: any) => (d.type === "wikilink" ? "url(#arrow)" : null)); .attr("stroke-dasharray", (d: any) => (d.type === "reference" ? "4 3" : null))
.attr("stroke-width", (d: any) => (d.type === "tag" ? 1 : 1.5))
.attr("marker-end", (d: any) => (d.type === "tag" ? null : "url(#arrow)"));
// Node groups // Node groups
const nodeSel = zoomG const nodeSel = zoomG
@@ -559,7 +563,7 @@ onUnmounted(() => {
<div <div
v-else-if="peekBody" v-else-if="peekBody"
class="prose peek-prose" class="prose peek-prose"
v-html="renderMarkdown(peekBody)" v-html="renderMarkdown(peekBody)" v-record-refs
/> />
<div v-else class="peek-empty">No content.</div> <div v-else class="peek-empty">No content.</div>
</div> </div>
+2 -1
View File
@@ -40,6 +40,7 @@ import UsageBadge from "@/components/UsageBadge.vue";
import { DEAD_WEIGHT_ADVICE } from "@/utils/deadWeight"; import { DEAD_WEIGHT_ADVICE } from "@/utils/deadWeight";
import { useToastStore } from "@/stores/toast"; import { useToastStore } from "@/stores/toast";
import { renderMarkdown } from "@/utils/markdown"; import { renderMarkdown } from "@/utils/markdown";
import { vRecordRefs } from "@/directives/recordRefs";
import { canWriteRecord } from "@/utils/permission"; import { canWriteRecord } from "@/utils/permission";
import { recordHref } from "@/utils/recordHref"; import { recordHref } from "@/utils/recordHref";
@@ -171,7 +172,7 @@ onMounted(load);
<div <div
v-if="insightHtml" v-if="insightHtml"
class="ld-insight markdown-body" class="ld-insight markdown-body"
v-html="insightHtml" v-html="insightHtml" v-record-refs
/> />
<p v-else class="ld-muted ld-empty"> <p v-else class="ld-muted ld-empty">
No detail was recorded — the claim above is the whole lesson. No detail was recorded — the claim above is the whole lesson.
+2 -1
View File
@@ -5,6 +5,7 @@ import type { NoteType } from "@/types/note";
import { useNotesStore } from "@/stores/notes"; import { useNotesStore } from "@/stores/notes";
import { useToastStore } from "@/stores/toast"; import { useToastStore } from "@/stores/toast";
import { renderMarkdown } from "@/utils/markdown"; import { renderMarkdown } from "@/utils/markdown";
import { vRecordRefs } from "@/directives/recordRefs";
import { useAssist, type NoteDraft } from "@/composables/useAssist"; import { useAssist, type NoteDraft } from "@/composables/useAssist";
import { useAutoSave } from "@/composables/useAutoSave"; import { useAutoSave } from "@/composables/useAutoSave";
import { useEditorGuards } from "@/composables/useEditorGuards"; import { useEditorGuards } from "@/composables/useEditorGuards";
@@ -439,7 +440,7 @@ onUnmounted(() => assist.clearSelection());
<div <div
v-else v-else
class="preview-pane prose" class="preview-pane prose"
v-html="renderedPreview" v-html="renderedPreview" v-record-refs
/> />
</Transition> </Transition>
</template> </template>
+11 -3
View File
@@ -3,6 +3,8 @@ import { onMounted, computed, ref, watch } from "vue";
import { useRoute, useRouter } from "vue-router"; import { useRoute, useRouter } from "vue-router";
import { useNotesStore } from "@/stores/notes"; import { useNotesStore } from "@/stores/notes";
import { renderMarkdown } from "@/utils/markdown"; import { renderMarkdown } from "@/utils/markdown";
import { vRecordRefs } from "@/directives/recordRefs";
import { recordHref } from "@/utils/recordHref";
import { relativeTime } from "@/composables/useRelativeTime"; import { relativeTime } from "@/composables/useRelativeTime";
import { apiPost, apiGet, apiPatch } from "@/api/client"; import { apiPost, apiGet, apiPatch } from "@/api/client";
import type { Note } from "@/types/note"; import type { Note } from "@/types/note";
@@ -14,7 +16,12 @@ import { Clock, Pencil, Link as LinkIcon } from "lucide-vue-next";
const route = useRoute(); const route = useRoute();
const router = useRouter(); const router = useRouter();
const store = useNotesStore(); const store = useNotesStore();
const backlinks = ref<{ type: string; id: number; title: string }[]>([]); /** What links here, and how: a `[[title]]` wikilink or a `#N` reference in a
* body or work log. */
const backlinks = ref<{
type: string; id: number; title: string;
is_task?: boolean; note_type?: string; via?: "wikilink" | "reference";
}[]>([]);
const converting = ref(false); const converting = ref(false);
const showShare = ref(false); const showShare = ref(false);
@@ -259,7 +266,7 @@ async function convertToTask() {
<div <div
class="body prose" class="body prose"
:class="{ 'prose--checklist': isListNote }" :class="{ 'prose--checklist': isListNote }"
v-html="renderedBody" v-html="renderedBody" v-record-refs
@click="onBodyClick" @click="onBodyClick"
@change="onBodyChange" @change="onBodyChange"
></div> ></div>
@@ -274,7 +281,8 @@ async function convertToTask() {
<router-link <router-link
v-for="link in backlinks" v-for="link in backlinks"
:key="`${link.type}-${link.id}`" :key="`${link.type}-${link.id}`"
:to="`/${link.type === 'note' ? 'notes' : 'tasks'}/${link.id}`" :to="recordHref({ id: link.id, is_task: link.is_task ?? link.type === 'task', note_type: link.note_type })"
:title="link.via === 'reference' ? `Cites #${noteId} in its text` : `Links here by title`"
class="backlink-card" class="backlink-card"
> >
<span :class="['backlink-type-badge', `badge-${link.type}`]">{{ link.type }}</span> <span :class="['backlink-type-badge', `badge-${link.type}`]">{{ link.type }}</span>
+29 -3
View File
@@ -1,5 +1,5 @@
<script setup lang="ts"> <script setup lang="ts">
import { ref, computed, onMounted, watch } from "vue"; import { ref, computed, onMounted, watch, nextTick } from "vue";
import { useRoute, useRouter } from "vue-router"; import { useRoute, useRouter } from "vue-router";
import { apiGet, apiPatch, apiDelete, apiPost, apiPut, apiErrorMessage } from "@/api/client"; import { apiGet, apiPatch, apiDelete, apiPost, apiPut, apiErrorMessage } from "@/api/client";
import { useAuthStore } from "@/stores/auth"; import { useAuthStore } from "@/stores/auth";
@@ -7,6 +7,7 @@ import { useToastStore } from "@/stores/toast";
import { useTasksStore } from "@/stores/tasks"; import { useTasksStore } from "@/stores/tasks";
import { relativeTime } from "@/composables/useRelativeTime"; import { relativeTime } from "@/composables/useRelativeTime";
import { renderMarkdown } from "@/utils/markdown"; import { renderMarkdown } from "@/utils/markdown";
import { vRecordRefs } from "@/directives/recordRefs";
import ShareDialog from "@/components/ShareDialog.vue"; import ShareDialog from "@/components/ShareDialog.vue";
import KindBadge from "@/components/KindBadge.vue"; import KindBadge from "@/components/KindBadge.vue";
import ProjectStatusBadge from "@/components/ProjectStatusBadge.vue"; import ProjectStatusBadge from "@/components/ProjectStatusBadge.vue";
@@ -585,8 +586,27 @@ async function saveForgePin() {
} }
} }
/** `?milestone=N` opens the board at that milestone: the Tasks tab, the
* milestone expanded and scrolled into view, its header focused. This is
* where a `milestone N` reference in any body leads. */
async function focusMilestoneFromRoute() {
const id = Number(route.query.milestone);
if (!id || !milestones.value.some((m) => m.id === id)) return;
activeTab.value = "tasks";
collapsedMilestones.value.delete(id);
await nextTick();
const header = document.querySelector<HTMLElement>(
`[data-milestone-id="${id}"] .milestone-header`,
);
header?.scrollIntoView({ block: "start", behavior: "smooth" });
header?.focus({ preventScroll: true });
}
watch(() => route.query.milestone, () => void focusMilestoneFromRoute());
onMounted(async () => { onMounted(async () => {
await loadProject(); await loadProject();
void focusMilestoneFromRoute();
loadTasks(); loadTasks();
loadNotes(); loadNotes();
loadDesignSystems(); loadDesignSystems();
@@ -985,9 +1005,15 @@ async function confirmDelete() {
</div> </div>
</div> </div>
<div v-for="group in milestoneGroups" :key="group.milestone?.id ?? 'unassigned'" class="milestone-group"> <div
v-for="group in milestoneGroups"
:key="group.milestone?.id ?? 'unassigned'"
class="milestone-group"
:data-milestone-id="group.milestone?.id"
>
<div <div
class="milestone-header" class="milestone-header"
tabindex="-1"
:class="{ clickable: renamingMilestoneId !== group.milestone?.id }" :class="{ clickable: renamingMilestoneId !== group.milestone?.id }"
:aria-expanded="!collapsedMilestones.has(groupKey(group))" :aria-expanded="!collapsedMilestones.has(groupKey(group))"
@click="renamingMilestoneId !== group.milestone?.id && toggleMilestoneCollapse(groupKey(group))" @click="renamingMilestoneId !== group.milestone?.id && toggleMilestoneCollapse(groupKey(group))"
@@ -1050,7 +1076,7 @@ async function confirmDelete() {
:class="['ms-plan-rendered', 'markdown-body', :class="['ms-plan-rendered', 'markdown-body',
{ 'ms-plan-clamped': isPlanClamped(group.milestone) }]" { 'ms-plan-clamped': isPlanClamped(group.milestone) }]"
@click="startEditPlan(group.milestone.id, group.milestone.body)" @click="startEditPlan(group.milestone.id, group.milestone.body)"
v-html="renderMarkdown(group.milestone.body || '')" v-html="renderMarkdown(group.milestone.body || '')" v-record-refs
></div> ></div>
<button <button
v-if="isPlanLong(group.milestone)" v-if="isPlanLong(group.milestone)"
+2 -1
View File
@@ -10,6 +10,7 @@ import {
import { useToastStore } from "@/stores/toast"; import { useToastStore } from "@/stores/toast";
import ConfirmDialog from "@/components/ConfirmDialog.vue"; import ConfirmDialog from "@/components/ConfirmDialog.vue";
import { renderMarkdown } from "@/utils/markdown"; import { renderMarkdown } from "@/utils/markdown";
import { vRecordRefs } from "@/directives/recordRefs";
import { canWriteRecord } from "@/utils/permission"; import { canWriteRecord } from "@/utils/permission";
const route = useRoute(); const route = useRoute();
@@ -185,7 +186,7 @@ async function confirmDelete() {
<section v-if="snippet.snippet.notes" class="notes"> <section v-if="snippet.snippet.notes" class="notes">
<h2 class="notes-heading">Notes</h2> <h2 class="notes-heading">Notes</h2>
<div class="prose" v-html="renderMarkdown(snippet.snippet.notes)" /> <div class="prose" v-html="renderMarkdown(snippet.snippet.notes)" v-record-refs />
</section> </section>
<div v-if="snippet.tags.length" class="tag-row"> <div v-if="snippet.tags.length" class="tag-row">
+2 -1
View File
@@ -5,6 +5,7 @@ import { useTasksStore } from "@/stores/tasks";
import { useNotesStore } from "@/stores/notes"; import { useNotesStore } from "@/stores/notes";
import { useToastStore } from "@/stores/toast"; import { useToastStore } from "@/stores/toast";
import { renderMarkdown } from "@/utils/markdown"; import { renderMarkdown } from "@/utils/markdown";
import { vRecordRefs } from "@/directives/recordRefs";
import { useAssist } from "@/composables/useAssist"; import { useAssist } from "@/composables/useAssist";
import { useAutoSave } from "@/composables/useAutoSave"; import { useAutoSave } from "@/composables/useAutoSave";
import { useEditorGuards } from "@/composables/useEditorGuards"; import { useEditorGuards } from "@/composables/useEditorGuards";
@@ -538,7 +539,7 @@ useEditorGuards(dirty, save);
<div <div
v-show="showPreview" v-show="showPreview"
class="preview-pane prose" class="preview-pane prose"
v-html="renderedPreview" v-html="renderedPreview" v-record-refs
/> />
</template> </template>
+4 -1
View File
@@ -144,7 +144,10 @@ async def create_note(
Args: Args:
title: Note title (required). title: Note title (required).
body: Markdown content. Supports [[wikilinks]] to other notes by title. body: Markdown content. Cite another record as `#N` (note, task,
lesson, snippet), `milestone N` or `rule N`; the web UI links each
one, titled on hover, and lists it in the target's backlinks.
`[[Title]]` links a note by its title.
tags: List of plain-string tags without # prefix, e.g. ["python", "ideas"]. tags: List of plain-string tags without # prefix, e.g. ["python", "ideas"].
project_id: Associate with a project (use 0 for no project / orphan note). project_id: Associate with a project (use 0 for no project / orphan note).
system_ids: Ids of the project's Systems to associate this note with system_ids: Ids of the project's Systems to associate this note with
+6 -1
View File
@@ -271,7 +271,9 @@ async def create_task(
Args: Args:
title: Task title (required). title: Task title (required).
body: Markdown description / notes for the task. body: Markdown description / notes for the task. Cite another record
as `#N` (note, task, lesson, snippet), `milestone N` or `rule N`;
the web UI links each one and lists it in the target's backlinks.
status: Initial status — one of: todo (default), in_progress, done, cancelled. status: Initial status — one of: todo (default), in_progress, done, cancelled.
priority: One of: low, medium, high, or 'none'. Omit (empty string) to leave unset. priority: One of: low, medium, high, or 'none'. Omit (empty string) to leave unset.
project_id: Associate with a project (0 = no project). project_id: Associate with a project (0 = no project).
@@ -482,6 +484,9 @@ async def add_task_log(task_id: int, content: str) -> dict:
cannot get from the body or the diff is what you tried, what you ruled cannot get from the body or the diff is what you tried, what you ruled
out, and where it actually stands. out, and where it actually stands.
Records named as `#N`, `milestone N` or `rule N` are links in the web UI,
and a `#N` here lists this task in that record's backlinks.
A log on an open task also marks it as being worked by this session — its A log on an open task also marks it as being worked by this session — its
`claim`. That is what brings the task and its newest `claim`. That is what brings the task and its newest
entries back to you after a compaction; it lapses by itself once the entries back to you after a compaction; it lapses by itself once the
+32
View File
@@ -6,6 +6,7 @@ from quart import Blueprint, jsonify, request
from grimoire.auth import login_required, get_current_user_id from grimoire.auth import login_required, get_current_user_id
from grimoire.routes.utils import not_found, parse_iso_date, parse_pagination from grimoire.routes.utils import not_found, parse_iso_date, parse_pagination
from grimoire.services import record_refs
from grimoire.services.access import can_write_note from grimoire.services.access import can_write_note
from grimoire.services.notes import ( from grimoire.services.notes import (
build_note_graph, build_note_graph,
@@ -194,6 +195,37 @@ async def resolve_title_route():
return jsonify(note.to_dict()) return jsonify(note.to_dict())
@notes_bp.route("/resolve-refs", methods=["POST"])
@login_required
async def resolve_refs_route():
"""What the record references in a rendered body point at.
Body: {"notes": [ids], "milestones": [ids], "rules": [ids]}. Answers the
same three keys, each a map of id -> {title, kind fields}, holding only the
records the caller may read. An id left out of the answer is drawn as a
reference that leads nowhere. The web UI calls this once per rendered body
to give each `#N`, `milestone N` and `rule N` link its route and its title.
"""
uid = get_current_user_id()
data = await request.get_json(silent=True) or {}
spaces: dict[str, list[int]] = {}
for key in ("notes", "milestones", "rules"):
raw = data.get(key) or []
if not isinstance(raw, list):
return jsonify({"error": f"{key} must be a list of ids"}), 400
try:
spaces[key] = [int(i) for i in raw]
except (TypeError, ValueError):
return jsonify({"error": f"{key} must be a list of ids"}), 400
if sum(len(v) for v in spaces.values()) > record_refs.RESOLVE_LIMIT:
return jsonify({
"error": f"at most {record_refs.RESOLVE_LIMIT} references per call",
}), 400
resolved = await record_refs.resolve_refs(uid, **spaces)
# JSON object keys are strings; say so here rather than in every caller.
return jsonify({k: {str(i): v for i, v in m.items()} for k, m in resolved.items()})
@notes_bp.route("/duplicates", methods=["GET"]) @notes_bp.route("/duplicates", methods=["GET"])
@login_required @login_required
async def find_duplicate_records_route(): async def find_duplicate_records_route():
+81 -18
View File
@@ -986,33 +986,80 @@ async def get_notes_by_ids(user_id: int, note_ids: list[int]) -> dict[int, Note]
async def get_backlinks(user_id: int, note_id: int) -> list[dict]: async def get_backlinks(user_id: int, note_id: int) -> list[dict]:
note = await get_note(user_id, note_id) """The records that link to this one, among those the caller may read.
if note is None:
return []
title = note.title Two ways to link: a `[[title]]` wikilink, and a `#N` reference in a body or
if not title: in a task's work log (most cross-references agents write are the second).
Each row says which one it was in `via`. A record reached both ways is
listed once, as a wikilink.
"""
from grimoire.models.task_log import TaskLog
from grimoire.services.access import readable_notes_clause
from grimoire.services.record_refs import referenced
found = await get_note_for_user(user_id, note_id)
if found is None:
return [] return []
note, _ = found
readable = readable_notes_clause(user_id)
rows: dict[int, dict] = {}
def _row(n: Note, via: str) -> dict:
return {
"type": "task" if n.is_task else "note",
"id": n.id,
"title": n.title,
"is_task": n.is_task,
"note_type": n.note_type or "note",
"via": via,
}
async with async_session() as session: async with async_session() as session:
escaped = title.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_") if note.title:
pattern = f"%[[{escaped}]]%" escaped = note.title.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
pattern_alias = f"%[[{escaped}|%" linking = (await session.execute(
select(Note).where(
readable,
Note.id != note_id,
Note.deleted_at.is_(None),
or_(Note.body.like(f"%[[{escaped}]]%"),
Note.body.like(f"%[[{escaped}|%")),
)
)).scalars().all()
for n in linking:
rows[n.id] = _row(n, "wikilink")
results = await session.execute( # LIKE narrows to bodies holding the digits after a `#`; `referenced`
select(Note.id, Note.title, Note.status).where( # then reads each one the way the renderer does, so `#12` does not
Note.user_id == user_id, # count as a link to 1, and "PR #12" is not a link at all.
needle = f"%#{note_id}%"
citing = (await session.execute(
select(Note).where(
readable,
Note.id != note_id, Note.id != note_id,
Note.deleted_at.is_(None), Note.deleted_at.is_(None),
or_(Note.body.like(pattern), Note.body.like(pattern_alias)), Note.body.like(needle),
) )
) )).scalars().all()
backlinks: list[dict] = [] for n in citing:
for row in results.fetchall(): if n.id not in rows and note_id in referenced(n.body)["notes"]:
link_type = "task" if row[2] is not None else "note" rows[n.id] = _row(n, "reference")
backlinks.append({"type": link_type, "id": row[0], "title": row[1]})
return backlinks logged = (await session.execute(
select(Note, TaskLog.content)
.join(TaskLog, TaskLog.task_id == Note.id)
.where(
readable,
Note.id != note_id,
Note.deleted_at.is_(None),
TaskLog.content.like(needle),
)
)).all()
for n, content in logged:
if n.id not in rows and note_id in referenced(content)["notes"]:
rows[n.id] = _row(n, "reference")
return list(rows.values())
_WIKILINK_RE = re.compile(r'\[\[([^\]|]+)(?:\|[^\]]+)?\]\]') _WIKILINK_RE = re.compile(r'\[\[([^\]|]+)(?:\|[^\]]+)?\]\]')
@@ -1071,6 +1118,22 @@ async def build_note_graph(
edge_set.add(pair) edge_set.add(pair)
edges.append({"source": n.id, "target": target_id, "type": "wikilink"}) edges.append({"source": n.id, "target": target_id, "type": "wikilink"})
# `#N` reference edges, read the way the renderer links them. Only between
# records already on the graph: a reference to something outside it (another
# project, a record the caller cannot read) has no node to end at.
from grimoire.services.record_refs import referenced
on_graph = {n.id for n in notes}
for n in notes:
if not n.body:
continue
for target_id in sorted(referenced(n.body)["notes"]):
if target_id in on_graph and target_id != n.id:
pair = (n.id, target_id)
if pair not in edge_set:
edge_set.add(pair)
edges.append({"source": n.id, "target": target_id, "type": "reference"})
# Build tag nodes + note→tag edges # Build tag nodes + note→tag edges
if include_shared_tags: if include_shared_tags:
tag_to_ids: dict[str, list[int]] = {} tag_to_ids: dict[str, list[int]] = {}
+124 -1
View File
@@ -1,4 +1,4 @@
"""Record references written into prose: refusing guessed ids, resolving placeholders, reading the ids a message names. """Record references written into prose: refusing guessed ids, resolving placeholders, reading the ids a message names, and saying what a body links to.
THE DEFECT THIS EXISTS FOR THE DEFECT THIS EXISTS FOR
@@ -41,6 +41,7 @@ restores and internal writers that legitimately carry numbers from elsewhere.
from __future__ import annotations from __future__ import annotations
import re import re
from collections.abc import Iterable
from sqlalchemy import func, select from sqlalchemy import func, select
@@ -209,6 +210,128 @@ def _prev_word(before: str) -> str:
return m.group(1).lower() if m else "" return m.group(1).lower() if m else ""
# ── References written into a record's prose ───────────────────────────────
#
# What a body, a work log or a plan names, read the way the web UI links it.
# `frontend/src/utils/recordRefs.ts` holds the same patterns and the same word
# list, and tests/test_record_ref_links.py reads that file and fails when its
# patterns or words differ from these.
#
# Three id spaces, three forms:
# `#N` a note, task, lesson or snippet (one sequence, the notes table)
# `milestone N` a milestone — what `{{ref:milestone}}` renders as
# `rule N` a rule; `preference N` too, since preferences are rules
# A `#N` after a word that names another numbering ("PR #198", "rule #34",
# "step #3") is not a note: `_OTHER_SPACE` above decides, exactly as it does for
# the numbers an operator names in a message.
PROSE_REF_RE = re.compile(r"(?<![\w/])\b(milestone|rule|preference)\s+#?(\d+)\b", re.IGNORECASE)
# Fenced and inline code: a pasted log or a snippet of source names nothing.
_CODE_RE = re.compile(r"```[\s\S]*?```|`[^`\n]+`")
def referenced(*texts: str | None) -> dict[str, set[int]]:
"""Every record these texts link to, by id space: notes, milestones, rules."""
out: dict[str, set[int]] = {"notes": set(), "milestones": set(), "rules": set()}
for text in texts:
if not text:
continue
text = _CODE_RE.sub(" ", text)
for m in PROSE_REF_RE.finditer(text):
space = "milestones" if m.group(1).lower() == "milestone" else "rules"
out[space].add(int(m.group(2)))
for m in REF_RE.finditer(text):
if _prev_word(text[:m.start()]) not in _OTHER_SPACE:
out["notes"].add(int(m.group(1)))
return out
# How many references one resolve call answers. A long plan cites a few dozen;
# past this the caller is listing, not rendering, and gets a 400 at the door.
RESOLVE_LIMIT = 200
async def resolve_refs(
user_id: int,
*,
notes: Iterable[int] = (),
milestones: Iterable[int] = (),
rules: Iterable[int] = (),
) -> dict[str, dict[int, dict]]:
"""What each referenced id IS, for the records this user may read.
An id that is missing, trashed or not readable is simply absent, and the
caller shows it as a reference that leads nowhere. The answer never says
which of the three it was: "not shared with you" and "does not exist" must
read the same, or the resolver becomes a way to probe other people's ids.
No pull is recorded. Hovering a link is not choosing to read the record;
the view it opens records that, the same as any other way of arriving.
"""
from grimoire.models.milestone import Milestone
from grimoire.services import rulebooks as rulebooks_svc
from grimoire.services.access import can_read_project, readable_notes_clause
out: dict[str, dict[int, dict]] = {"notes": {}, "milestones": {}, "rules": {}}
note_ids = sorted({int(i) for i in notes})
milestone_ids = sorted({int(i) for i in milestones})
rule_ids = sorted({int(i) for i in rules})
async with async_session() as session:
if note_ids:
rows = (await session.execute(
select(Note).where(
Note.id.in_(note_ids),
Note.deleted_at.is_(None),
readable_notes_clause(user_id),
)
)).scalars().all()
for n in rows:
out["notes"][n.id] = {
"id": n.id,
"title": n.title or "",
"is_task": n.is_task,
"note_type": n.note_type or "note",
"status": n.status,
"task_kind": n.task_kind if n.is_task else None,
}
if milestone_ids:
rows = (await session.execute(
select(Milestone).where(
Milestone.id.in_(milestone_ids), Milestone.deleted_at.is_(None),
)
)).scalars().all()
readable_projects: dict[int, bool] = {}
for ms in rows:
if ms.user_id != user_id:
pid = ms.project_id
if pid is None:
continue
if pid not in readable_projects:
readable_projects[pid] = await can_read_project(user_id, pid)
if not readable_projects[pid]:
continue
out["milestones"][ms.id] = {
"id": ms.id,
"title": ms.title or "",
"project_id": ms.project_id,
"status": ms.status,
}
# One lookup per rule: readability runs through rulebook ownership and
# project ownership, which `get_rule` already resolves. A body names a few.
for rid in rule_ids:
rule = await rulebooks_svc.get_rule(rid, user_id)
if rule is not None:
out["rules"][rule.id] = {
"id": rule.id,
"title": rule.title or "",
"kind": getattr(rule, "kind", None) or "rule",
}
return out
def _next_word(after: str) -> str: def _next_word(after: str) -> str:
m = _NEXT_WORD_RE.match(after) m = _NEXT_WORD_RE.match(after)
return m.group(1).lower() if m else "" return m.group(1).lower() if m else ""
+6 -2
View File
@@ -1,11 +1,15 @@
import re import re
_CODE_FENCE_RE = re.compile(r"```[\s\S]*?```|`[^`\n]+`") _CODE_FENCE_RE = re.compile(r"```[\s\S]*?```|`[^`\n]+`")
_TAG_RE = re.compile(r"(?<!\w)#([\w][\w-]*(?:/[\w][\w-]*)*)") # A `#` token made only of digits is a record reference (`#3127` names note
# 3127, see services/record_refs.py), never a tag. Digits followed by more of a
# tag (`#2fa`, `#123-notes`) is still a tag. frontend/src/utils/tags.ts holds the
# same pattern.
_TAG_RE = re.compile(r"(?<!\w)#(?!\d+(?![\w/-]))([\w][\w-]*(?:/[\w][\w-]*)*)")
def extract_tags(body: str) -> list[str]: def extract_tags(body: str) -> list[str]:
"""Extract #tags from body text, ignoring code blocks.""" """Extract #tags from body text, ignoring code blocks and record references."""
cleaned = _CODE_FENCE_RE.sub("", body) cleaned = _CODE_FENCE_RE.sub("", body)
tags = _TAG_RE.findall(cleaned) tags = _TAG_RE.findall(cleaned)
return sorted(set(tags)) return sorted(set(tags))
+106
View File
@@ -0,0 +1,106 @@
"""Real-Postgres proof that a reference resolves only to what the reader may open, and that backlinks follow `#N`.
What mocks cannot show: the access clause applied in SQL to a shared project,
the LIKE prefilter not admitting `#12` as a link to 1, and a citation in a work
log reaching the cited record's backlinks.
"""
import pytest
import pytest_asyncio
from grimoire.models import async_session
from grimoire.models.milestone import Milestone
from grimoire.models.note import Note
from grimoire.models.project import Project
from grimoire.models.share import ProjectShare
from grimoire.models.task_log import TaskLog
from grimoire.services.notes import get_backlinks
from grimoire.services.record_refs import resolve_refs
from tests.helpers import ensure_user
pytestmark = [pytest.mark.integration, pytest.mark.usefixtures("_dispose_engine", "_no_embedding")]
@pytest_asyncio.fixture
async def world():
async with async_session() as s:
owner = await ensure_user(s, "ref_links_owner")
reader = await ensure_user(s, "ref_links_reader")
stranger = await ensure_user(s, "ref_links_stranger")
shared = Project(user_id=owner.id, title="Shared project")
private = Project(user_id=owner.id, title="Private project")
s.add_all([shared, private])
await s.flush()
s.add(ProjectShare(project_id=shared.id, shared_with_user_id=reader.id,
permission="viewer", invited_by=owner.id))
target = Note(user_id=owner.id, project_id=shared.id, title="Target", body="")
hidden = Note(user_id=owner.id, project_id=private.id, title="Hidden", body="")
lesson = Note(user_id=owner.id, project_id=shared.id, title="A lesson",
body="", note_type="lesson")
ms_shared = Milestone(user_id=owner.id, project_id=shared.id, title="Shared plan")
ms_private = Milestone(user_id=owner.id, project_id=private.id, title="Private plan")
s.add_all([target, hidden, lesson, ms_shared, ms_private])
await s.flush()
ids = {
"owner": owner.id, "reader": reader.id, "stranger": stranger.id,
"shared": shared.id, "target": target.id, "hidden": hidden.id,
"lesson": lesson.id, "ms_shared": ms_shared.id, "ms_private": ms_private.id,
}
await s.commit()
return ids
async def test_the_owner_resolves_every_kind_with_its_route_fields(world):
out = await resolve_refs(
world["owner"],
notes=[world["target"], world["lesson"], world["hidden"]],
milestones=[world["ms_shared"], world["ms_private"]],
)
assert set(out["notes"]) == {world["target"], world["lesson"], world["hidden"]}
assert out["notes"][world["lesson"]]["note_type"] == "lesson"
assert out["notes"][world["target"]]["is_task"] is False
assert out["milestones"][world["ms_shared"]]["project_id"] == world["shared"]
async def test_a_collaborator_resolves_the_shared_project_and_nothing_else(world):
out = await resolve_refs(
world["reader"],
notes=[world["target"], world["hidden"]],
milestones=[world["ms_shared"], world["ms_private"]],
)
assert set(out["notes"]) == {world["target"]}
assert set(out["milestones"]) == {world["ms_shared"]}
async def test_unreadable_and_nonexistent_ids_read_the_same(world):
"""Absent either way, so the resolver cannot be used to probe for ids."""
out = await resolve_refs(world["stranger"], notes=[world["target"], 2_000_000_000])
assert out["notes"] == {}
async def test_backlinks_follow_references_in_bodies_and_work_logs(world):
t = world["target"]
async with async_session() as s:
citing = Note(user_id=world["owner"], project_id=world["shared"],
title="Cites it", body=f"Builds on #{t}.")
logged = Note(user_id=world["owner"], project_id=world["shared"],
title="Logs it", body="", status="todo")
other_space = Note(user_id=world["owner"], project_id=world["shared"],
title="Other numbering", body=f"See PR #{t}.")
longer = Note(user_id=world["owner"], project_id=world["shared"],
title="Longer id", body=f"See #{t}0.")
s.add_all([citing, logged, other_space, longer])
await s.flush()
s.add(TaskLog(task_id=logged.id, user_id=world["owner"], content=f"Fixed with #{t} in mind."))
ids = {"citing": citing.id, "logged": logged.id}
await s.commit()
rows = await get_backlinks(world["owner"], t)
by_id = {r["id"]: r for r in rows}
assert set(by_id) == {ids["citing"], ids["logged"]}
assert by_id[ids["citing"]]["via"] == "reference"
assert by_id[ids["logged"]]["is_task"] is True
# The collaborator sees the same backlinks, since every record is in the
# project shared with them; a stranger cannot open the target at all.
assert {r["id"] for r in await get_backlinks(world["reader"], t)} == set(by_id)
assert await get_backlinks(world["stranger"], t) == []
+108
View File
@@ -0,0 +1,108 @@
"""What a body cites, and that the web UI and the backend read it the same way.
A `#N` in prose names a note, task, lesson or snippet; `milestone N` and
`rule N` name records in their own id spaces. The backend reads these for
backlinks and graph edges (services/record_refs.referenced); the web UI links
them (frontend/src/utils/recordRefs.ts). A token made only of digits is never a
tag, on either side.
There is no frontend test runner, so the TS half is held to the Python half by
reading its source: the two patterns and the word list must be the same text.
"""
from __future__ import annotations
import re
from pathlib import Path
import pytest
from grimoire.services import record_refs
from grimoire.services.record_refs import referenced
from grimoire.utils.tags import extract_tags
FRONTEND = Path(__file__).resolve().parents[1] / "frontend" / "src"
REFS_TS = FRONTEND / "utils" / "recordRefs.ts"
TAGS_TS = FRONTEND / "utils" / "tags.ts"
def _refs(notes=(), milestones=(), rules=()):
return {"notes": set(notes), "milestones": set(milestones), "rules": set(rules)}
@pytest.mark.parametrize(("text", "expected"), [
("see #123", _refs(notes={123})),
("shipped #5110–#5119", _refs(notes={5110, 5119})),
# "step" names a position in a plan ("step #3"), the same reading the
# message parser uses, so a #N right after it stays plain.
("step #3 of the plan", _refs()),
("(#4286) and #4290.", _refs(notes={4286, 4290})),
("#v2 is a tag", _refs()),
("a colour #123abc", _refs()),
("inline `#12` is code", _refs()),
("```\nlog line #77\n```\nafter #78", _refs(notes={78})),
("PR #198 and run #4", _refs()),
("rule #34 and rule 10", _refs(rules={34, 10})),
("preference 12 holds", _refs(rules={12})),
("part of milestone 639", _refs(milestones={639})),
('Part of milestone 7 "Ship it"; next is #9 "Step two".', _refs(notes={9}, milestones={7})),
("an entity &#123; and a path a/#9", _refs()),
("", _refs()),
])
def test_referenced_reads_what_the_ui_links(text, expected):
assert referenced(text) == expected
def test_referenced_ignores_none_among_texts():
assert referenced(None, "#5", None) == _refs(notes={5})
@pytest.mark.parametrize(("body", "tags"), [
("#123", []),
("cites (#4286)", []),
("#5110–#5119", []),
("#v2 #123abc #2fa", ["123abc", "2fa", "v2"]),
("#123-notes and #12/x", ["12/x", "123-notes"]),
("#python #review", ["python", "review"]),
])
def test_a_token_of_digits_alone_is_never_a_tag(body, tags):
assert extract_tags(body) == tags
# ── The TS reader is the same text as the Python one ───────────────────────
def _ts_regex(src: str, name: str) -> str:
m = re.search(rf"export const {name} = /(.+?)/[gimsuy]*;", src)
assert m, f"{name} is no longer a regex literal in {REFS_TS.name}"
return m.group(1)
def test_the_ui_reads_note_references_with_the_backend_pattern():
src = REFS_TS.read_text()
assert _ts_regex(src, "NOTE_REF_RE") == record_refs.REF_RE.pattern
def test_the_ui_reads_milestone_and_rule_references_with_the_backend_pattern():
src = REFS_TS.read_text()
assert _ts_regex(src, "PROSE_REF_RE") == record_refs.PROSE_REF_RE.pattern
# Python compiles it IGNORECASE; the literal must carry `i` too.
assert re.search(r"export const PROSE_REF_RE = /.+?/[gmsuy]*i[gmsuy]*;", src)
assert record_refs.PROSE_REF_RE.flags & re.IGNORECASE
def test_the_ui_skips_the_same_other_numberings():
src = REFS_TS.read_text()
m = re.search(r"export const OTHER_SPACE: readonly string\[\] = \[(.*?)\];", src, re.S)
assert m, f"OTHER_SPACE is no longer a string-array literal in {REFS_TS.name}"
words = set(re.findall(r'"([a-z]+)"', m.group(1)))
assert words == set(record_refs._OTHER_SPACE)
def test_both_tag_patterns_leave_digits_alone_to_the_reference_reader():
from grimoire.utils import tags as tags_py
guard = r"#(?!\d+(?![\w/-]))"
assert guard in tags_py._TAG_RE.pattern
ts = TAGS_TS.read_text()
m = re.search(r"export const TAG_RE = /(.+?)/g;", ts)
assert m, f"TAG_RE is no longer a regex literal in {TAGS_TS.name}"
assert guard in m.group(1)