attraverso 0.6.0 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +33 -6
- package/assets/migrations/0016_brave_squadron_sinister.sql +77 -0
- package/assets/migrations/meta/0016_snapshot.json +1844 -0
- package/assets/migrations/meta/_journal.json +7 -0
- package/lib/index.js +577 -18
- package/migrations/0016_brave_squadron_sinister.sql +77 -0
- package/migrations/meta/0016_snapshot.json +1844 -0
- package/migrations/meta/_journal.json +7 -0
- package/package.json +1 -1
- package/server.js +1037 -102
- package/viewer/assets/favicon-DAARTY8o.svg +24 -0
- package/viewer/assets/{index-t0yugwqv.js → index-BlJrlICb.js} +27 -20
- package/viewer/assets/index-D4LIwbZD.css +1 -0
- package/viewer/index.html +3 -3
- package/viewer/assets/favicon-BUxCK25s.svg +0 -13
- package/viewer/assets/index-CNwAsUDo.css +0 -1
package/lib/index.js
CHANGED
|
@@ -92,6 +92,7 @@ var schema_exports = /* @__PURE__ */ __exportAll({
|
|
|
92
92
|
projectNext: () => projectNext,
|
|
93
93
|
projects: () => projects,
|
|
94
94
|
scopedDependencies: () => scopedDependencies,
|
|
95
|
+
sourceReferences: () => sourceReferences,
|
|
95
96
|
users: () => users
|
|
96
97
|
});
|
|
97
98
|
/**
|
|
@@ -374,6 +375,41 @@ var layoutPositions = pgTable("layout_positions", {
|
|
|
374
375
|
x: integer("x").notNull(),
|
|
375
376
|
y: integer("y").notNull()
|
|
376
377
|
}, (t) => [primaryKey({ columns: [t.projectId, t.node] })]);
|
|
378
|
+
/**
|
|
379
|
+
* Source references (`CTX-13`): where a claim in some prose came from. The text carries a pointer after the claim,
|
|
380
|
+
* `[ref r7k2]`, and this table carries everything else - one row per *source*, the rows sharing a `key` making one
|
|
381
|
+
* reference, so a claim gathers sources over time ("elevated whenever it has additional sources") without a
|
|
382
|
+
* second table holding what they share. Text with no pointer is the agent's own reasoning, and has no row.
|
|
383
|
+
*
|
|
384
|
+
* - **The owner is an item or a context section**, exactly one, by foreign key, so deleting either cascades its
|
|
385
|
+
* references away. Repeated on each of a reference's rows, and kept to one owner per key by the trigger rather
|
|
386
|
+
* than an index, since several rows share a key.
|
|
387
|
+
* - **`quoted_text` is the text this source vouched for when it was added**: a record of a moment, like an event
|
|
388
|
+
* payload, never kept in sync, and how "text changed since" is told without storing a flag.
|
|
389
|
+
* - **`source` is an open vocabulary**, like every other one here (`user`, `test`, `search`, `docs` today), validated
|
|
390
|
+
* by the domain layer rather than a database enum.
|
|
391
|
+
* - **Retired, never deleted**, so what a claim was once backed by stays legible.
|
|
392
|
+
*
|
|
393
|
+
* Not `references`: that is a reserved word in SQL.
|
|
394
|
+
*/
|
|
395
|
+
var sourceReferences = pgTable("source_references", {
|
|
396
|
+
id: text("id").primaryKey().$defaultFn(uuidv7),
|
|
397
|
+
projectId: text("project_id").notNull().references(() => projects.id, { onDelete: "cascade" }),
|
|
398
|
+
key: text("key").notNull(),
|
|
399
|
+
itemId: text("item_id").references(() => items.id, { onDelete: "cascade" }),
|
|
400
|
+
sectionId: text("section_id").references(() => contextSections.id, { onDelete: "cascade" }),
|
|
401
|
+
source: text("source").notNull(),
|
|
402
|
+
detail: text("detail").notNull(),
|
|
403
|
+
quotedText: text("quoted_text").notNull(),
|
|
404
|
+
actor: text("actor").notNull(),
|
|
405
|
+
recordedAt: text("recorded_at").notNull().$defaultFn(timestamp),
|
|
406
|
+
retiredAt: text("retired_at")
|
|
407
|
+
}, (t) => [
|
|
408
|
+
check("source_references_one_owner", sql`(${t.itemId} IS NULL) <> (${t.sectionId} IS NULL)`),
|
|
409
|
+
index("source_references_project_key").on(t.projectId, t.key),
|
|
410
|
+
index("source_references_item").on(t.itemId),
|
|
411
|
+
index("source_references_section").on(t.sectionId)
|
|
412
|
+
]);
|
|
377
413
|
var events = pgTable("events", {
|
|
378
414
|
id: text("id").primaryKey().$defaultFn(uuidv7),
|
|
379
415
|
projectId: text("project_id").references(() => projects.id, { onDelete: "cascade" }),
|
|
@@ -461,6 +497,8 @@ var _0013_kind_bloodscream_default = "CREATE TABLE \"scoped_dependencies\" (\n \
|
|
|
461
497
|
var _0014_past_chronomancer_default = "ALTER TABLE \"items\" ADD COLUMN \"start_on\" text;--> statement-breakpoint\nALTER TABLE \"items\" ADD COLUMN \"due_on\" text;--> statement-breakpoint\nCREATE INDEX \"items_project_due\" ON \"items\" USING btree (\"project_id\",\"due_on\");";
|
|
462
498
|
// src/db/migrations/0015_stormy_blindfold.sql?raw
|
|
463
499
|
var _0015_stormy_blindfold_default = "CREATE TABLE \"layout_positions\" (\n \"project_id\" text NOT NULL,\n \"node\" text NOT NULL,\n \"x\" integer NOT NULL,\n \"y\" integer NOT NULL,\n CONSTRAINT \"layout_positions_project_id_node_pk\" PRIMARY KEY(\"project_id\",\"node\")\n);\n--> statement-breakpoint\nALTER TABLE \"layout_positions\" ADD CONSTRAINT \"layout_positions_project_id_projects_id_fk\" FOREIGN KEY (\"project_id\") REFERENCES \"public\".\"projects\"(\"id\") ON DELETE cascade ON UPDATE no action;";
|
|
500
|
+
// src/db/migrations/0016_brave_squadron_sinister.sql?raw
|
|
501
|
+
var _0016_brave_squadron_sinister_default = "CREATE TABLE \"source_references\" (\n \"id\" text PRIMARY KEY NOT NULL,\n \"project_id\" text NOT NULL,\n \"key\" text NOT NULL,\n \"item_id\" text,\n \"section_id\" text,\n \"source\" text NOT NULL,\n \"detail\" text NOT NULL,\n \"quoted_text\" text NOT NULL,\n \"actor\" text NOT NULL,\n \"recorded_at\" text NOT NULL,\n \"retired_at\" text,\n CONSTRAINT \"source_references_one_owner\" CHECK ((\"source_references\".\"item_id\" IS NULL) <> (\"source_references\".\"section_id\" IS NULL))\n);\n--> statement-breakpoint\nALTER TABLE \"source_references\" ADD CONSTRAINT \"source_references_project_id_projects_id_fk\" FOREIGN KEY (\"project_id\") REFERENCES \"public\".\"projects\"(\"id\") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint\nALTER TABLE \"source_references\" ADD CONSTRAINT \"source_references_item_id_items_id_fk\" FOREIGN KEY (\"item_id\") REFERENCES \"public\".\"items\"(\"id\") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint\nALTER TABLE \"source_references\" ADD CONSTRAINT \"source_references_section_id_context_sections_id_fk\" FOREIGN KEY (\"section_id\") REFERENCES \"public\".\"context_sections\"(\"id\") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint\nCREATE INDEX \"source_references_project_key\" ON \"source_references\" USING btree (\"project_id\",\"key\");--> statement-breakpoint\nCREATE INDEX \"source_references_item\" ON \"source_references\" USING btree (\"item_id\");--> statement-breakpoint\nCREATE INDEX \"source_references_section\" ON \"source_references\" USING btree (\"section_id\");--> statement-breakpoint\n-- CTX-13: every live source reference's pointer is in its owner's text, and a key has one owner. Hand-written: a\n-- trigger is beyond what drizzle-kit generates. Deferred to commit, so a reference and its pointer can arrive in\n-- either order within one transaction. Each firing checks only the item, section or key that changed. Loading a\n-- plan file sets attraverso.loading_plan for its transaction and is let through: a hand edit that broke a\n-- pointer must still load (stale is a state a plan loads in, never a refusal to load), and apm:check reports it.\n-- A pointer is \"[ref key]\" or the expanded \"[ref key: ...]\", matched exactly so r7k2 never matches r7k29.\nCREATE FUNCTION \"source_references_check\"() RETURNS trigger LANGUAGE plpgsql AS $$\nDECLARE\n bad text;\nBEGIN\n IF current_setting('attraverso.loading_plan', true) = 'on' THEN\n RETURN NULL;\n END IF;\n IF TG_TABLE_NAME = 'items' THEN\n SELECT r.key INTO bad FROM source_references r JOIN items i ON i.id = r.item_id\n WHERE r.item_id = NEW.id AND r.retired_at IS NULL\n AND position('[ref ' || r.key || ']' IN coalesce(i.body, '')) = 0\n AND position('[ref ' || r.key || ':' IN coalesce(i.body, '')) = 0\n LIMIT 1;\n ELSIF TG_TABLE_NAME = 'context_sections' THEN\n SELECT r.key INTO bad FROM source_references r JOIN context_sections c ON c.id = r.section_id\n WHERE r.section_id = NEW.id AND r.retired_at IS NULL\n AND position('[ref ' || r.key || ']' IN c.content) = 0\n AND position('[ref ' || r.key || ':' IN c.content) = 0\n LIMIT 1;\n ELSE\n SELECT r.key INTO bad FROM source_references r\n LEFT JOIN items i ON i.id = r.item_id LEFT JOIN context_sections c ON c.id = r.section_id\n WHERE r.project_id = NEW.project_id AND r.key = NEW.key AND r.retired_at IS NULL\n AND position('[ref ' || r.key || ']' IN coalesce(i.body, c.content, '')) = 0\n AND position('[ref ' || r.key || ':' IN coalesce(i.body, c.content, '')) = 0\n LIMIT 1;\n IF bad IS NULL THEN\n SELECT r.key INTO bad FROM source_references r\n WHERE r.project_id = NEW.project_id AND r.key = NEW.key AND r.retired_at IS NULL\n GROUP BY r.key HAVING count(DISTINCT coalesce(r.item_id, r.section_id)) > 1;\n IF bad IS NOT NULL THEN\n RAISE EXCEPTION 'source reference % has more than one owner', bad USING ERRCODE = 'check_violation';\n END IF;\n END IF;\n END IF;\n IF bad IS NOT NULL THEN\n RAISE EXCEPTION 'source reference % is live but its pointer is not in the text', bad USING ERRCODE = 'check_violation';\n END IF;\n RETURN NULL;\nEND\n$$;\n--> statement-breakpoint\nCREATE CONSTRAINT TRIGGER \"source_references_on_items\" AFTER UPDATE OF \"body\" ON \"items\"\n DEFERRABLE INITIALLY DEFERRED FOR EACH ROW EXECUTE FUNCTION \"source_references_check\"();\n--> statement-breakpoint\nCREATE CONSTRAINT TRIGGER \"source_references_on_sections\" AFTER UPDATE OF \"content\" ON \"context_sections\"\n DEFERRABLE INITIALLY DEFERRED FOR EACH ROW EXECUTE FUNCTION \"source_references_check\"();\n--> statement-breakpoint\nCREATE CONSTRAINT TRIGGER \"source_references_on_rows\" AFTER INSERT OR UPDATE ON \"source_references\"\n DEFERRABLE INITIALLY DEFERRED FOR EACH ROW EXECUTE FUNCTION \"source_references_check\"();\n";
|
|
464
502
|
var _journal_default = {
|
|
465
503
|
version: "7",
|
|
466
504
|
dialect: "postgresql",
|
|
@@ -576,6 +614,13 @@ var _journal_default = {
|
|
|
576
614
|
"when": 1794545387434,
|
|
577
615
|
"tag": "0015_stormy_blindfold",
|
|
578
616
|
"breakpoints": true
|
|
617
|
+
},
|
|
618
|
+
{
|
|
619
|
+
"idx": 16,
|
|
620
|
+
"version": "7",
|
|
621
|
+
"when": 1794774084272,
|
|
622
|
+
"tag": "0016_brave_squadron_sinister",
|
|
623
|
+
"breakpoints": true
|
|
579
624
|
}
|
|
580
625
|
]
|
|
581
626
|
};
|
|
@@ -597,7 +642,8 @@ var files = /* #__PURE__ */ Object.assign({
|
|
|
597
642
|
"./migrations/0012_smiling_butterfly.sql": _0012_smiling_butterfly_default,
|
|
598
643
|
"./migrations/0013_kind_bloodscream.sql": _0013_kind_bloodscream_default,
|
|
599
644
|
"./migrations/0014_past_chronomancer.sql": _0014_past_chronomancer_default,
|
|
600
|
-
"./migrations/0015_stormy_blindfold.sql": _0015_stormy_blindfold_default
|
|
645
|
+
"./migrations/0015_stormy_blindfold.sql": _0015_stormy_blindfold_default,
|
|
646
|
+
"./migrations/0016_brave_squadron_sinister.sql": _0016_brave_squadron_sinister_default
|
|
601
647
|
});
|
|
602
648
|
/** The breakpoint drizzle-kit writes between statements, and that drizzle's reader splits on. */
|
|
603
649
|
var BREAKPOINT = "--> statement-breakpoint";
|
|
@@ -1028,6 +1074,23 @@ var attachmentSchema = z.object({
|
|
|
1028
1074
|
at: z.string(),
|
|
1029
1075
|
actor: z.string()
|
|
1030
1076
|
});
|
|
1077
|
+
/**
|
|
1078
|
+
* One source behind a source reference (`CTX-13`). References are written where their pointer is - under the item
|
|
1079
|
+
* whose body holds it, keyed by the pointer's key - so reading the file shows a claim's sources beside the item,
|
|
1080
|
+
* as comments are. The row's `id` rides along like a comment's, so a round trip keeps it and an edit can address it.
|
|
1081
|
+
* `text` is the exact text this source vouched for; `retired` is set when its pointer was removed.
|
|
1082
|
+
*/
|
|
1083
|
+
var referenceSchema = z.object({
|
|
1084
|
+
source: z.string(),
|
|
1085
|
+
detail: z.string(),
|
|
1086
|
+
text: z.string(),
|
|
1087
|
+
id: z.string(),
|
|
1088
|
+
at: z.string(),
|
|
1089
|
+
actor: z.string(),
|
|
1090
|
+
retired: z.string().optional()
|
|
1091
|
+
});
|
|
1092
|
+
/** Pointer key -> its sources, oldest first. */
|
|
1093
|
+
var referencesSchema = z.record(z.string().regex(/^[a-z0-9]+$/, "a reference key is lowercase letters and digits"), z.array(referenceSchema));
|
|
1031
1094
|
/** One project's layout: node id -> "x,y", whole numbers on the layout's grid. */
|
|
1032
1095
|
var layoutSchema = z.record(z.string(), z.string().regex(/^-?\d+,-?\d+$/, "a layout position is \"x,y\" in whole numbers"));
|
|
1033
1096
|
var itemSchema = z.object({
|
|
@@ -1059,7 +1122,8 @@ var itemSchema = z.object({
|
|
|
1059
1122
|
comments: z.array(commentSchema).optional(),
|
|
1060
1123
|
/** Accepted for old plan files, never written: see `readComments` (CTX-2). */
|
|
1061
1124
|
notes: z.array(commentSchema).optional(),
|
|
1062
|
-
attachments: z.array(attachmentSchema).optional()
|
|
1125
|
+
attachments: z.array(attachmentSchema).optional(),
|
|
1126
|
+
references: referencesSchema.optional()
|
|
1063
1127
|
});
|
|
1064
1128
|
var retiredSessionSchema = z.array(z.unknown());
|
|
1065
1129
|
var projectSchema = z.object({
|
|
@@ -1074,6 +1138,7 @@ var projectSchema = z.object({
|
|
|
1074
1138
|
updated_at: z.string(),
|
|
1075
1139
|
archived_at: z.string().optional(),
|
|
1076
1140
|
context: z.record(z.string(), z.string()).optional(),
|
|
1141
|
+
context_references: z.record(z.string(), referencesSchema).optional(),
|
|
1077
1142
|
areas: z.array(areaSchema),
|
|
1078
1143
|
items: z.array(itemSchema),
|
|
1079
1144
|
sessions: retiredSessionSchema.optional(),
|
|
@@ -1160,6 +1225,28 @@ async function exportStore(db, ownerId) {
|
|
|
1160
1225
|
actor: a.actor
|
|
1161
1226
|
})) : void 0;
|
|
1162
1227
|
const layoutRows = await db.select().from(layoutPositions).where(eq(layoutPositions.projectId, p.id)).orderBy(asc(layoutPositions.node));
|
|
1228
|
+
const referenceRows = await db.select().from(sourceReferences).where(eq(sourceReferences.projectId, p.id)).orderBy(asc(sourceReferences.key), asc(sourceReferences.recordedAt), asc(sourceReferences.id));
|
|
1229
|
+
const sectionHeading = new Map(sectionRows.map((s) => [s.id, s.heading]));
|
|
1230
|
+
const referencesByItem = /* @__PURE__ */ new Map();
|
|
1231
|
+
const referencesBySection = /* @__PURE__ */ new Map();
|
|
1232
|
+
for (const r of referenceRows) {
|
|
1233
|
+
const [owners, owner] = r.itemId !== null ? [referencesByItem, r.itemId] : [referencesBySection, sectionHeading.get(r.sectionId)];
|
|
1234
|
+
const byKey = owners.get(owner) ?? owners.set(owner, {}).get(owner);
|
|
1235
|
+
(byKey[r.key] ??= []).push({
|
|
1236
|
+
source: r.source,
|
|
1237
|
+
detail: r.detail,
|
|
1238
|
+
text: r.quotedText,
|
|
1239
|
+
id: r.id,
|
|
1240
|
+
at: r.recordedAt,
|
|
1241
|
+
actor: r.actor,
|
|
1242
|
+
retired: opt(r.retiredAt)
|
|
1243
|
+
});
|
|
1244
|
+
}
|
|
1245
|
+
const contextReferences = {};
|
|
1246
|
+
for (const s of sectionRows) {
|
|
1247
|
+
const refs = referencesBySection.get(s.heading);
|
|
1248
|
+
if (refs !== void 0) contextReferences[s.heading] = refs;
|
|
1249
|
+
}
|
|
1163
1250
|
const fmtComments = (rows) => rows.length > 0 ? rows.map((n) => ({
|
|
1164
1251
|
body: n.body,
|
|
1165
1252
|
audience: n.audience,
|
|
@@ -1179,6 +1266,7 @@ async function exportStore(db, ownerId) {
|
|
|
1179
1266
|
updated_at: p.updatedAt,
|
|
1180
1267
|
archived_at: opt(p.archivedAt),
|
|
1181
1268
|
context: sectionRows.length > 0 ? context : void 0,
|
|
1269
|
+
context_references: Object.keys(contextReferences).length > 0 ? contextReferences : void 0,
|
|
1182
1270
|
comments: fmtComments(projectComments),
|
|
1183
1271
|
attachments: fmtAttachments(projectAttachments),
|
|
1184
1272
|
areas: areaRows.map((a) => ({
|
|
@@ -1209,7 +1297,8 @@ async function exportStore(db, ownerId) {
|
|
|
1209
1297
|
closed_at: opt(i.closedAt),
|
|
1210
1298
|
deleted_at: opt(i.deletedAt),
|
|
1211
1299
|
comments: fmtComments(commentsByItem.get(i.id) ?? []),
|
|
1212
|
-
attachments: fmtAttachments(attachmentsByItem.get(i.id) ?? [])
|
|
1300
|
+
attachments: fmtAttachments(attachmentsByItem.get(i.id) ?? []),
|
|
1301
|
+
references: referencesByItem.get(i.id)
|
|
1213
1302
|
};
|
|
1214
1303
|
}),
|
|
1215
1304
|
layout: layoutRows.length > 0 ? Object.fromEntries(layoutRows.map((row) => [row.node, `${row.x},${row.y}`])) : void 0
|
|
@@ -1223,6 +1312,7 @@ async function importStore(db, store) {
|
|
|
1223
1312
|
await db.transaction((tx) => insertStore(tx, store));
|
|
1224
1313
|
}
|
|
1225
1314
|
async function insertStore(tx, store, owner) {
|
|
1315
|
+
await tx.execute(sql`select set_config('attraverso.loading_plan', 'on', true)`);
|
|
1226
1316
|
const ownerId = owner ?? (await ensureUserIn(tx, LOCAL_IDENTITY)).id;
|
|
1227
1317
|
for (const p of store.projects) {
|
|
1228
1318
|
await tx.insert(projects).values({
|
|
@@ -1311,12 +1401,43 @@ async function insertStore(tx, store, owner) {
|
|
|
1311
1401
|
});
|
|
1312
1402
|
if (layoutValues.length > 0) await tx.insert(layoutPositions).values(layoutValues);
|
|
1313
1403
|
const contextEntries = Object.entries(p.context ?? {});
|
|
1314
|
-
|
|
1404
|
+
const headingToId = /* @__PURE__ */ new Map();
|
|
1405
|
+
if (contextEntries.length > 0) {
|
|
1406
|
+
const inserted = await tx.insert(contextSections).values(contextEntries.map(([heading, content], index) => ({
|
|
1407
|
+
projectId: p.id,
|
|
1408
|
+
heading,
|
|
1409
|
+
content,
|
|
1410
|
+
sortOrder: index
|
|
1411
|
+
}))).returning({
|
|
1412
|
+
id: contextSections.id,
|
|
1413
|
+
heading: contextSections.heading
|
|
1414
|
+
});
|
|
1415
|
+
for (const row of inserted) headingToId.set(row.heading, row.id);
|
|
1416
|
+
}
|
|
1417
|
+
const referenceValues = [...p.items.flatMap((i) => Object.entries(i.references ?? {}).map(([key, rows]) => ({
|
|
1418
|
+
key,
|
|
1419
|
+
rows,
|
|
1420
|
+
itemId: refToId.get(i.ref) ?? null,
|
|
1421
|
+
sectionId: null
|
|
1422
|
+
}))), ...Object.entries(p.context_references ?? {}).flatMap(([heading, refs]) => Object.entries(refs).map(([key, rows]) => ({
|
|
1423
|
+
key,
|
|
1424
|
+
rows,
|
|
1425
|
+
itemId: null,
|
|
1426
|
+
sectionId: headingToId.get(heading) ?? null
|
|
1427
|
+
})))].flatMap(({ key, rows, itemId, sectionId }) => itemId === null && sectionId === null ? [] : rows.map((r) => ({
|
|
1428
|
+
id: r.id,
|
|
1315
1429
|
projectId: p.id,
|
|
1316
|
-
|
|
1317
|
-
|
|
1318
|
-
|
|
1430
|
+
key,
|
|
1431
|
+
itemId,
|
|
1432
|
+
sectionId,
|
|
1433
|
+
source: r.source,
|
|
1434
|
+
detail: r.detail,
|
|
1435
|
+
quotedText: r.text,
|
|
1436
|
+
actor: r.actor,
|
|
1437
|
+
recordedAt: r.at,
|
|
1438
|
+
retiredAt: r.retired ?? null
|
|
1319
1439
|
})));
|
|
1440
|
+
if (referenceValues.length > 0) await tx.insert(sourceReferences).values(referenceValues);
|
|
1320
1441
|
const commentValues = [...readComments(p).map((c) => ({
|
|
1321
1442
|
comment: c,
|
|
1322
1443
|
itemId: null
|
|
@@ -1356,9 +1477,418 @@ async function insertStore(tx, store, owner) {
|
|
|
1356
1477
|
/** The plan as text, in the one layout every writer shares (`IMP-19`, see `format.ts`). */
|
|
1357
1478
|
var stringifyStore = (store) => stringify(store, YAML_FORMAT);
|
|
1358
1479
|
z.record(z.string(), layoutSchema);
|
|
1480
|
+
z.record(z.string(), z.object({
|
|
1481
|
+
items: z.record(z.string(), referencesSchema).optional(),
|
|
1482
|
+
context: z.record(z.string(), referencesSchema).optional()
|
|
1483
|
+
}));
|
|
1359
1484
|
function parseStore(text) {
|
|
1360
1485
|
return storeSchema.parse(parse(text));
|
|
1361
1486
|
}
|
|
1487
|
+
// scripts/references.ts
|
|
1488
|
+
/**
|
|
1489
|
+
* Source reference pointers in prose (`CTX-13`): where they are, and what text each one stands behind.
|
|
1490
|
+
*
|
|
1491
|
+
* A claim is followed by a pointer, `[ref r7k2]`, and the reference's sources live in `source_references`. This
|
|
1492
|
+
* module is the one parser every reader shares - the tools, `apm:check` and the viewer - so it is Node-free, like
|
|
1493
|
+
* `tickets.ts`: two parsers that split a body differently would make one claim stale in one place and fine in
|
|
1494
|
+
* another.
|
|
1495
|
+
*
|
|
1496
|
+
* **What a pointer covers is set by where it sits, never stored:**
|
|
1497
|
+
*
|
|
1498
|
+
* - **Inline, it covers the text before it** in the same markdown block, back to the previous pointer or the
|
|
1499
|
+
* block's start - the footnote convention, a citation after its claim. A block is a paragraph, one list item,
|
|
1500
|
+
* one table row, a heading, or a code block.
|
|
1501
|
+
* - **On its own line, it covers the whole group above it**: a paragraph, a whole list, a whole table, a code block.
|
|
1502
|
+
* Pointer-only lines in between are skipped, so two sources can stand behind one table.
|
|
1503
|
+
*
|
|
1504
|
+
* **What is not a pointer:** anything inside a code span or a fenced block, so documentation of this syntax never
|
|
1505
|
+
* trips it; an escaped `\[ref`; one followed by `(` or `:`, which markdown reads as a link or a link definition
|
|
1506
|
+
* (`[ref docs](https://...)`); and only `[ref ` followed by a key opens one, so task boxes and footnotes never do.
|
|
1507
|
+
* Indented code is not masked, deliberately: four-space list continuations are far commoner in these bodies.
|
|
1508
|
+
*
|
|
1509
|
+
* Deliberately a small line scanner rather than a markdown parser: the server has no markdown dependency at
|
|
1510
|
+
* runtime, and the few block shapes that matter here are easy to tell apart by their first characters.
|
|
1511
|
+
*/
|
|
1512
|
+
/** A key is short lowercase letters and digits, generated by the tool: never shaped like an item's ref. */
|
|
1513
|
+
var KEY = "[a-z0-9]+";
|
|
1514
|
+
/** How long an expanded pointer's detail may run: `get_item` keeps what it shows well under it, and the bound keeps a
|
|
1515
|
+
* run of unclosed `[ref k:` from costing quadratic time on hostile input. */
|
|
1516
|
+
var EXPANSION = "[^\\]\\n]{0,3000}";
|
|
1517
|
+
/** `[ref key]`, or the expanded `[ref key: ...]` that `get_item` returns and an agent may send straight back. Not
|
|
1518
|
+
* escaped, and not followed by `(` or `:`, which would make it a link or a link definition. */
|
|
1519
|
+
var POINTER = new RegExp(`(?<!\\\\)\\[ref (${KEY})(?::${EXPANSION})?\\](?![(:])`, "g");
|
|
1520
|
+
/** `[ref ` not followed by a well-formed key and its close: a pointer someone meant to write and got wrong. */
|
|
1521
|
+
var MALFORMED = new RegExp(`(?<!\\\\)\\[ref (?!${KEY}(?:\\]|:${EXPANSION}\\]))`, "g");
|
|
1522
|
+
/**
|
|
1523
|
+
* The comparison form of some covered text: whitespace collapsed, Unicode NFC, and trimmed of what surrounds a
|
|
1524
|
+
* claim rather than belonging to it - a list marker or heading hashes in front, a table's pipes, the punctuation
|
|
1525
|
+
* left at the start of a span by the previous pointer's sentence.
|
|
1526
|
+
*/
|
|
1527
|
+
function normaliseClaim(text) {
|
|
1528
|
+
return text.normalize("NFC").replace(/^[ \t]*>[ \t]?/gm, "").replace(/\s+/g, " ").replace(/^\s*(?:[-*+]|\d+[.)]|#{1,6})\s+/, "").replace(/^[\s|.,;:!?)]+/, "").replace(/[\s|]+$/, "").trim();
|
|
1529
|
+
}
|
|
1530
|
+
/** A fence marker opening a line: three or more backticks or tildes. */
|
|
1531
|
+
var fenceOf = (line) => /^\s*(`{3,}|~{3,})/.exec(line)?.[1];
|
|
1532
|
+
/** Whether `marker` closes a block opened by `fence`: the same character, at least as many of it. */
|
|
1533
|
+
var closes = (fence, marker) => marker[0] === fence[0] && marker.length >= fence.length;
|
|
1534
|
+
/** The text with every code span and fenced block blanked to spaces, keeping offsets, so pointers in code vanish. */
|
|
1535
|
+
function maskCode(text) {
|
|
1536
|
+
const lines = text.split("\n");
|
|
1537
|
+
let fence;
|
|
1538
|
+
return lines.map((line) => {
|
|
1539
|
+
const marker = fenceOf(line);
|
|
1540
|
+
if (fence === void 0 && marker !== void 0) {
|
|
1541
|
+
fence = marker;
|
|
1542
|
+
return " ".repeat(line.length);
|
|
1543
|
+
}
|
|
1544
|
+
if (fence !== void 0) {
|
|
1545
|
+
if (marker !== void 0 && closes(fence, marker)) fence = void 0;
|
|
1546
|
+
return " ".repeat(line.length);
|
|
1547
|
+
}
|
|
1548
|
+
return line;
|
|
1549
|
+
}).join("\n").split(/(\n[ \t]*\n)/).map(maskSpans).join("");
|
|
1550
|
+
}
|
|
1551
|
+
/**
|
|
1552
|
+
* Blank the inline code spans in one paragraph: a run of backticks closed by the next run of exactly the same
|
|
1553
|
+
* length. A run with no partner is literal text, and the scan carries on after it, as CommonMark has it - so a
|
|
1554
|
+
* stray backtick in prose ("the ` key") hides nothing after it.
|
|
1555
|
+
*/
|
|
1556
|
+
function maskSpans(paragraph) {
|
|
1557
|
+
const runs = [...paragraph.matchAll(/`+/g)].map((m) => ({
|
|
1558
|
+
at: m.index,
|
|
1559
|
+
length: m[0].length
|
|
1560
|
+
}));
|
|
1561
|
+
const nextSame = new Array(runs.length).fill(-1);
|
|
1562
|
+
const seen = /* @__PURE__ */ new Map();
|
|
1563
|
+
for (let i = runs.length - 1; i >= 0; i--) {
|
|
1564
|
+
nextSame[i] = seen.get(runs[i].length) ?? -1;
|
|
1565
|
+
seen.set(runs[i].length, i);
|
|
1566
|
+
}
|
|
1567
|
+
const pieces = [];
|
|
1568
|
+
let last = 0;
|
|
1569
|
+
for (let i = 0; i < runs.length; i++) {
|
|
1570
|
+
const open = runs[i];
|
|
1571
|
+
const close = nextSame[i];
|
|
1572
|
+
if (close === -1) continue;
|
|
1573
|
+
const end = runs[close].at + open.length;
|
|
1574
|
+
pieces.push(paragraph.slice(last, open.at), " ".repeat(end - open.at));
|
|
1575
|
+
last = end;
|
|
1576
|
+
i = close;
|
|
1577
|
+
}
|
|
1578
|
+
return last === 0 ? paragraph : pieces.join("") + paragraph.slice(last);
|
|
1579
|
+
}
|
|
1580
|
+
/**
|
|
1581
|
+
* Split a text into blocks by its lines, with offsets into the original text. A paragraph runs until a blank line
|
|
1582
|
+
* or a line that opens a block of its own; a list item takes the unmarked lines after it (its lazy continuation);
|
|
1583
|
+
* a heading and a table row are one line each; a fenced block runs to its closing fence. Consecutive list items
|
|
1584
|
+
* share a group, even across a blank line, as do consecutive table rows, which is what an own-line pointer covers.
|
|
1585
|
+
*/
|
|
1586
|
+
function blocks(text) {
|
|
1587
|
+
const out = [];
|
|
1588
|
+
let group = 0;
|
|
1589
|
+
let offset = 0;
|
|
1590
|
+
let open = null;
|
|
1591
|
+
let fence;
|
|
1592
|
+
let afterBlank = false;
|
|
1593
|
+
for (const line of text.split("\n")) {
|
|
1594
|
+
const start = offset;
|
|
1595
|
+
const end = offset + line.length;
|
|
1596
|
+
offset = end + 1;
|
|
1597
|
+
const marker = fenceOf(line);
|
|
1598
|
+
if (fence !== void 0) {
|
|
1599
|
+
open.end = end;
|
|
1600
|
+
if (marker !== void 0 && closes(fence, marker)) {
|
|
1601
|
+
fence = void 0;
|
|
1602
|
+
open = null;
|
|
1603
|
+
}
|
|
1604
|
+
continue;
|
|
1605
|
+
}
|
|
1606
|
+
if (marker !== void 0) {
|
|
1607
|
+
fence = marker;
|
|
1608
|
+
open = {
|
|
1609
|
+
kind: "code",
|
|
1610
|
+
group: ++group,
|
|
1611
|
+
start,
|
|
1612
|
+
end
|
|
1613
|
+
};
|
|
1614
|
+
out.push(open);
|
|
1615
|
+
continue;
|
|
1616
|
+
}
|
|
1617
|
+
if (line.trim() === "") {
|
|
1618
|
+
open = null;
|
|
1619
|
+
afterBlank = true;
|
|
1620
|
+
continue;
|
|
1621
|
+
}
|
|
1622
|
+
const wasBlank = afterBlank;
|
|
1623
|
+
afterBlank = false;
|
|
1624
|
+
const kind = /^\s*#{1,6}\s/.test(line) ? "heading" : /^\s*\|/.test(line) ? "table" : /^\s*(?:[-*+]|\d+[.)])\s/.test(line) ? "list" : null;
|
|
1625
|
+
if (kind === null && open !== null && (open.kind === "paragraph" || open.kind === "list")) {
|
|
1626
|
+
open.end = end;
|
|
1627
|
+
continue;
|
|
1628
|
+
}
|
|
1629
|
+
const last = out[out.length - 1];
|
|
1630
|
+
const joins = kind !== null && last !== void 0 && last.kind === kind && (kind === "list" || !wasBlank);
|
|
1631
|
+
const block = {
|
|
1632
|
+
kind: kind ?? "paragraph",
|
|
1633
|
+
group: joins ? last.group : ++group,
|
|
1634
|
+
start,
|
|
1635
|
+
end
|
|
1636
|
+
};
|
|
1637
|
+
out.push(block);
|
|
1638
|
+
open = block.kind === "heading" || block.kind === "table" ? null : block;
|
|
1639
|
+
}
|
|
1640
|
+
return out;
|
|
1641
|
+
}
|
|
1642
|
+
/**
|
|
1643
|
+
* Every pointer in `text`, with what it covers, and every problem a writer should be told about: a malformed
|
|
1644
|
+
* pointer, the same key twice, and a pointer line directly under a table row, which markdown reads as another row
|
|
1645
|
+
* of the table rather than a pointer below it (the blank line nobody sees).
|
|
1646
|
+
*/
|
|
1647
|
+
function parsePointers(text) {
|
|
1648
|
+
const cached = parsed.get(text);
|
|
1649
|
+
if (cached !== void 0) return cached;
|
|
1650
|
+
const result = Object.freeze(parseUncached(text));
|
|
1651
|
+
Object.freeze(result.pointers);
|
|
1652
|
+
Object.freeze(result.problems);
|
|
1653
|
+
parsed.set(text, result);
|
|
1654
|
+
if (parsed.size > PARSE_CACHE) parsed.delete(parsed.keys().next().value);
|
|
1655
|
+
return result;
|
|
1656
|
+
}
|
|
1657
|
+
/** How many texts' answers `parsePointers` keeps: enough for a write's before and after, its tool reply, and a
|
|
1658
|
+
* read or two in between, without holding on to a whole plan's bodies. Oldest out first. */
|
|
1659
|
+
var PARSE_CACHE = 16;
|
|
1660
|
+
var parsed = /* @__PURE__ */ new Map();
|
|
1661
|
+
function parseUncached(text) {
|
|
1662
|
+
const masked = maskCode(text);
|
|
1663
|
+
const all = blocks(text);
|
|
1664
|
+
const pointers = [];
|
|
1665
|
+
const problems = [];
|
|
1666
|
+
const seen = /* @__PURE__ */ new Set();
|
|
1667
|
+
for (const match of masked.matchAll(MALFORMED)) {
|
|
1668
|
+
const snippet = text.slice(match.index, match.index + 16).split("\n")[0];
|
|
1669
|
+
problems.push({
|
|
1670
|
+
at: match.index,
|
|
1671
|
+
problem: `"${snippet}" is not a pointer: write [ref <key>], where a key is lowercase letters and digits`
|
|
1672
|
+
});
|
|
1673
|
+
}
|
|
1674
|
+
/** The original text of [from, to) with its pointers taken out, normalised: what a pointer covers. Code stays
|
|
1675
|
+
* in, since a claim can be about a command; only pointers, found in the masked copy, are removed. */
|
|
1676
|
+
const covered = (from, to) => {
|
|
1677
|
+
let out = "";
|
|
1678
|
+
let last = from;
|
|
1679
|
+
for (const m of masked.slice(from, to).matchAll(POINTER)) {
|
|
1680
|
+
out += text.slice(last, from + m.index) + " ";
|
|
1681
|
+
last = from + m.index + m[0].length;
|
|
1682
|
+
}
|
|
1683
|
+
return normaliseClaim(out + text.slice(last, to));
|
|
1684
|
+
};
|
|
1685
|
+
all.forEach((block, index) => {
|
|
1686
|
+
const inBlock = [...masked.slice(block.start, block.end).matchAll(POINTER)].map((m) => ({
|
|
1687
|
+
key: m[1],
|
|
1688
|
+
at: block.start + m.index,
|
|
1689
|
+
written: m[0]
|
|
1690
|
+
}));
|
|
1691
|
+
if (inBlock.length === 0) return;
|
|
1692
|
+
if (normaliseClaim(masked.slice(block.start, block.end).replace(POINTER, " ")) === "") {
|
|
1693
|
+
const above = all.slice(0, index).reverse().find((candidate) => candidate.kind === "code" || normaliseClaim(masked.slice(candidate.start, candidate.end).replace(POINTER, " ")) !== "");
|
|
1694
|
+
if (above !== void 0 && above.kind === "table" && !/\n\s*\n/.test(text.slice(above.end, block.start))) problems.push({
|
|
1695
|
+
at: inBlock[0].at,
|
|
1696
|
+
problem: `put a blank line between the table and [ref ${inBlock[0].key}], or markdown reads it as another row`
|
|
1697
|
+
});
|
|
1698
|
+
const covers = (above === void 0 ? [] : all.filter((candidate) => candidate.group === above.group && candidate.end <= block.start)).map((b) => covered(b.start, b.end)).filter(Boolean).join(" ");
|
|
1699
|
+
for (const p of inBlock) pointers.push({
|
|
1700
|
+
...p,
|
|
1701
|
+
covers: normaliseClaim(covers)
|
|
1702
|
+
});
|
|
1703
|
+
return;
|
|
1704
|
+
}
|
|
1705
|
+
let from = block.start;
|
|
1706
|
+
for (const p of inBlock) {
|
|
1707
|
+
const lineStart = text.lastIndexOf("\n", p.at - 1) + 1;
|
|
1708
|
+
const lineEnd = text.indexOf("\n", p.at) === -1 ? text.length : text.indexOf("\n", p.at);
|
|
1709
|
+
if (block.kind === "list" && lineStart > block.start && normaliseClaim(masked.slice(lineStart, lineEnd).replace(POINTER, " ")) === "") problems.push({
|
|
1710
|
+
at: p.at,
|
|
1711
|
+
problem: `put a blank line between the list and [ref ${p.key}], or markdown reads it as part of the last item`
|
|
1712
|
+
});
|
|
1713
|
+
pointers.push({
|
|
1714
|
+
...p,
|
|
1715
|
+
covers: covered(from, p.at)
|
|
1716
|
+
});
|
|
1717
|
+
from = p.at + p.written.length;
|
|
1718
|
+
}
|
|
1719
|
+
});
|
|
1720
|
+
for (const p of pointers) if (p.covers === "") problems.push({
|
|
1721
|
+
at: p.at,
|
|
1722
|
+
problem: `[ref ${p.key}] has nothing before it to stand behind: put it straight after its claim`
|
|
1723
|
+
});
|
|
1724
|
+
for (const p of pointers) {
|
|
1725
|
+
if (seen.has(p.key)) problems.push({
|
|
1726
|
+
at: p.at,
|
|
1727
|
+
problem: `[ref ${p.key}] appears twice: a key stands behind one claim`
|
|
1728
|
+
});
|
|
1729
|
+
seen.add(p.key);
|
|
1730
|
+
}
|
|
1731
|
+
return {
|
|
1732
|
+
pointers,
|
|
1733
|
+
problems
|
|
1734
|
+
};
|
|
1735
|
+
}
|
|
1736
|
+
/** The text with every expanded pointer reduced to its bare form, `[ref key: ...]` to `[ref key]`, outside code -
|
|
1737
|
+
* what is stored, whatever `get_item` returned and the writer sent back. */
|
|
1738
|
+
function bareForm(text) {
|
|
1739
|
+
const masked = maskCode(text);
|
|
1740
|
+
let out = "";
|
|
1741
|
+
let last = 0;
|
|
1742
|
+
for (const match of masked.matchAll(POINTER)) {
|
|
1743
|
+
out += text.slice(last, match.index) + `[ref ${match[1]}]`;
|
|
1744
|
+
last = match.index + match[0].length;
|
|
1745
|
+
}
|
|
1746
|
+
return out + text.slice(last);
|
|
1747
|
+
}
|
|
1748
|
+
/**
|
|
1749
|
+
* `path:line[-line][:column]@commit`, e.g. `packages/core/src/domain/items.ts:308-339@345a746`. Repo-relative rather
|
|
1750
|
+
* than a hosting provider's URL, so it works in a private repo, a fork and the open export alike; a viewer can still
|
|
1751
|
+
* make a link of it where it knows the host. Null when the detail is not one, which the writing tool refuses.
|
|
1752
|
+
*/
|
|
1753
|
+
function parseCodeRef(detail) {
|
|
1754
|
+
const match = /^([^\s:@][^\s:@]*):([1-9]\d*)(?:-([1-9]\d*))?(?::([1-9]\d*))?@([0-9a-f]{7,40})$/.exec(detail.trim());
|
|
1755
|
+
if (match === null) return null;
|
|
1756
|
+
if (match[1].startsWith("/") || match[1].includes("\\") || match[1].split("/").includes("..")) return null;
|
|
1757
|
+
const from = Number(match[2]);
|
|
1758
|
+
const to = match[3] === void 0 ? from : Number(match[3]);
|
|
1759
|
+
if (to < from) return null;
|
|
1760
|
+
return {
|
|
1761
|
+
path: match[1],
|
|
1762
|
+
from,
|
|
1763
|
+
to,
|
|
1764
|
+
...match[4] === void 0 ? {} : { column: Number(match[4]) },
|
|
1765
|
+
commit: match[5]
|
|
1766
|
+
};
|
|
1767
|
+
}
|
|
1768
|
+
// src/domain/references.ts
|
|
1769
|
+
/**
|
|
1770
|
+
* Source references (`CTX-13`): where a claim in some prose came from.
|
|
1771
|
+
*
|
|
1772
|
+
* The text carries a pointer after the claim, `[ref r7k2]`, and `source_references` carries one row per source
|
|
1773
|
+
* behind it. Everything here is advisory - nothing a writer does to the prose is refused over a reference - except
|
|
1774
|
+
* the one rule the database itself enforces at commit: **a live reference's pointer is in its owner's text**, so a
|
|
1775
|
+
* pointer cannot vanish while its reference still claims to stand behind something. The domain keeps that rule
|
|
1776
|
+
* true for every tool write by retiring, in the same transaction, the references whose pointers an edit removed;
|
|
1777
|
+
* the trigger is the backstop for every other path.
|
|
1778
|
+
*/
|
|
1779
|
+
/**
|
|
1780
|
+
* Retire every live reference of `owner` whose pointer `text` no longer carries, and say which keys they were.
|
|
1781
|
+
*
|
|
1782
|
+
* Called by every write that replaces an owner's prose, inside its transaction, so the commit-time check finds
|
|
1783
|
+
* nothing to object to. Retired rather than deleted: what a claim was once backed by stays legible, and the event
|
|
1784
|
+
* for the edit records which references went with it.
|
|
1785
|
+
*/
|
|
1786
|
+
async function retireRemovedPointers(tx, owner, text) {
|
|
1787
|
+
const ownedBy = "itemId" in owner ? eq(sourceReferences.itemId, owner.itemId) : eq(sourceReferences.sectionId, owner.sectionId);
|
|
1788
|
+
const live = await tx.select({ key: sourceReferences.key }).from(sourceReferences).where(and(ownedBy, isNull(sourceReferences.retiredAt)));
|
|
1789
|
+
const pointed = new Set(parsePointers(text).pointers.map((p) => p.key));
|
|
1790
|
+
const gone = [...new Set(live.map((row) => row.key))].filter((key) => !pointed.has(key)).sort();
|
|
1791
|
+
if (gone.length === 0) return [];
|
|
1792
|
+
const now = timestamp();
|
|
1793
|
+
for (const key of gone) await tx.update(sourceReferences).set({ retiredAt: now }).where(and(ownedBy, eq(sourceReferences.key, key), isNull(sourceReferences.retiredAt)));
|
|
1794
|
+
return gone;
|
|
1795
|
+
}
|
|
1796
|
+
/** Where a claim's source can come from. `agent` is the default for anything unreferenced and is never written. */
|
|
1797
|
+
var SOURCE_KINDS = [
|
|
1798
|
+
"user",
|
|
1799
|
+
"test",
|
|
1800
|
+
"search",
|
|
1801
|
+
"docs",
|
|
1802
|
+
"code"
|
|
1803
|
+
];
|
|
1804
|
+
/** A different advisory-lock namespace from ref allocation's, so the two never queue behind each other. */
|
|
1805
|
+
var REFERENCE_LOCK = 7172013;
|
|
1806
|
+
/**
|
|
1807
|
+
* Add sources to the references in `text`, after it has been written, inside the writing transaction.
|
|
1808
|
+
*
|
|
1809
|
+
* Each key must have its pointer in the text - the source stands behind *that* claim, and records the text it
|
|
1810
|
+
* covers now as what it vouched for - and must not be live under another owner. Serialised per project by an
|
|
1811
|
+
* advisory lock, because "one key, one owner" is a read-then-write: under READ COMMITTED two writers giving one
|
|
1812
|
+
* key to different items at once would both pass the check (found in the `CTX-13` spike, the same race `OPS-2`
|
|
1813
|
+
* fixed for ref allocation). The commit-time trigger would still refuse the second, but as a bare failure; the
|
|
1814
|
+
* lock turns it into a named one.
|
|
1815
|
+
*/
|
|
1816
|
+
async function addSources(tx, projectId, owner, text, sources, actor) {
|
|
1817
|
+
const keys = Object.keys(sources);
|
|
1818
|
+
if (keys.length === 0) return [];
|
|
1819
|
+
await tx.execute(sql`SELECT pg_advisory_xact_lock(${REFERENCE_LOCK}, hashtext(${projectId}))`);
|
|
1820
|
+
const covers = new Map(parsePointers(text).pointers.map((p) => [p.key, p.covers]));
|
|
1821
|
+
const ownerId = "itemId" in owner ? owner.itemId : owner.sectionId;
|
|
1822
|
+
const rows = [];
|
|
1823
|
+
for (const key of keys) {
|
|
1824
|
+
const claim = covers.get(key);
|
|
1825
|
+
if (claim === void 0) throw new Error(`no [ref ${key}] in the text: write it straight after the claim it stands behind, as [ref ${key}]`);
|
|
1826
|
+
if (claim === "") throw new Error(`[ref ${key}] has no claim before it: put it straight after the sentence it stands behind`);
|
|
1827
|
+
if ((await tx.select({
|
|
1828
|
+
itemId: sourceReferences.itemId,
|
|
1829
|
+
sectionId: sourceReferences.sectionId
|
|
1830
|
+
}).from(sourceReferences).where(and(eq(sourceReferences.projectId, projectId), eq(sourceReferences.key, key), isNull(sourceReferences.retiredAt)))).some((row) => (row.itemId ?? row.sectionId) !== ownerId)) throw new Error(`reference ${key} already stands behind a claim elsewhere in this project: choose another key`);
|
|
1831
|
+
for (const source of [sources[key]].flat()) {
|
|
1832
|
+
if (!SOURCE_KINDS.includes(source.source)) throw new Error(`"${source.source}" is not a source: use one of ${SOURCE_KINDS.join(", ")} (unreferenced text is your own reasoning)`);
|
|
1833
|
+
if (source.detail.trim() === "") throw new Error(`a ${source.source} source needs its detail: the command, URL or file, or the user's words verbatim`);
|
|
1834
|
+
if (source.source === "code" && parseCodeRef(source.detail) === null) throw new Error(`"${source.detail}" is not a code reference: write path:line or path:from-to, optionally :column, then @commit, e.g. src/db/schema.ts:120-140@345a746`);
|
|
1835
|
+
rows.push({
|
|
1836
|
+
projectId,
|
|
1837
|
+
key,
|
|
1838
|
+
itemId: "itemId" in owner ? owner.itemId : null,
|
|
1839
|
+
sectionId: "sectionId" in owner ? owner.sectionId : null,
|
|
1840
|
+
source: source.source,
|
|
1841
|
+
detail: source.detail.trim(),
|
|
1842
|
+
quotedText: claim,
|
|
1843
|
+
actor
|
|
1844
|
+
});
|
|
1845
|
+
}
|
|
1846
|
+
}
|
|
1847
|
+
if (rows.length === 0) return [];
|
|
1848
|
+
await tx.insert(sourceReferences).values(rows);
|
|
1849
|
+
return rows.map((row) => ({
|
|
1850
|
+
key: row.key,
|
|
1851
|
+
source: row.source,
|
|
1852
|
+
detail: row.detail
|
|
1853
|
+
})).sort((a, b) => a.key.localeCompare(b.key));
|
|
1854
|
+
}
|
|
1855
|
+
/** The live sources behind an owner's references, oldest first within each key. */
|
|
1856
|
+
async function liveSources(db, owner) {
|
|
1857
|
+
const ownedBy = "itemId" in owner ? eq(sourceReferences.itemId, owner.itemId) : eq(sourceReferences.sectionId, owner.sectionId);
|
|
1858
|
+
return db.select({
|
|
1859
|
+
key: sourceReferences.key,
|
|
1860
|
+
source: sourceReferences.source,
|
|
1861
|
+
detail: sourceReferences.detail,
|
|
1862
|
+
quotedText: sourceReferences.quotedText,
|
|
1863
|
+
recordedAt: sourceReferences.recordedAt
|
|
1864
|
+
}).from(sourceReferences).where(and(ownedBy, isNull(sourceReferences.retiredAt))).orderBy(asc(sourceReferences.key), asc(sourceReferences.recordedAt), asc(sourceReferences.id));
|
|
1865
|
+
}
|
|
1866
|
+
/**
|
|
1867
|
+
* The sourced claims an edit touched, old text against new, so the writer sees them in the same reply rather than
|
|
1868
|
+
* finding out on the next read. Nothing is refused: a changed claim keeps its sources and will read "text changed
|
|
1869
|
+
* since"; a removed pointer has already been retired.
|
|
1870
|
+
*/
|
|
1871
|
+
function referenceChanges(before, after, sources) {
|
|
1872
|
+
const was = new Map(parsePointers(before).pointers.map((p) => [p.key, p.covers]));
|
|
1873
|
+
const now = new Map(parsePointers(after).pointers.map((p) => [p.key, p.covers]));
|
|
1874
|
+
return [...new Set(sources.map((s) => s.key))].sort().flatMap((key) => {
|
|
1875
|
+
const summary = sources.filter((s) => s.key === key).map((s) => `${s.source} ${s.recordedAt.slice(0, 10)}`).join(", ");
|
|
1876
|
+
if (!now.has(key)) return was.has(key) ? [{
|
|
1877
|
+
key,
|
|
1878
|
+
kind: "retired",
|
|
1879
|
+
sources: summary
|
|
1880
|
+
}] : [];
|
|
1881
|
+
const before = was.get(key);
|
|
1882
|
+
const after = now.get(key);
|
|
1883
|
+
return before !== void 0 && before !== after ? [{
|
|
1884
|
+
key,
|
|
1885
|
+
kind: "changed",
|
|
1886
|
+
sources: summary,
|
|
1887
|
+
before,
|
|
1888
|
+
after
|
|
1889
|
+
}] : [];
|
|
1890
|
+
});
|
|
1891
|
+
}
|
|
1362
1892
|
// src/domain/context.ts
|
|
1363
1893
|
/**
|
|
1364
1894
|
* Context sections (CTX): the project's living narrative as named prose blocks - "Goals", "Assumptions",
|
|
@@ -1403,6 +1933,7 @@ async function orderAfter(tx, projectId, after, movingHeading) {
|
|
|
1403
1933
|
return index * 16 + 8;
|
|
1404
1934
|
}
|
|
1405
1935
|
async function setSection(db, input, actor) {
|
|
1936
|
+
const content = bareForm(input.content);
|
|
1406
1937
|
return mutate(db, actor, async (tx) => {
|
|
1407
1938
|
const existing = maybeOne(await tx.select().from(contextSections).where(and(eq(contextSections.projectId, input.projectId), eq(contextSections.heading, input.heading))));
|
|
1408
1939
|
const now = timestamp();
|
|
@@ -1410,27 +1941,38 @@ async function setSection(db, input, actor) {
|
|
|
1410
1941
|
const after = one(await tx.insert(contextSections).values({
|
|
1411
1942
|
projectId: input.projectId,
|
|
1412
1943
|
heading: input.heading,
|
|
1413
|
-
content
|
|
1944
|
+
content,
|
|
1414
1945
|
sortOrder: order,
|
|
1415
1946
|
createdAt: now,
|
|
1416
1947
|
updatedAt: now
|
|
1417
1948
|
}).onConflictDoUpdate({
|
|
1418
1949
|
target: [contextSections.projectId, contextSections.heading],
|
|
1419
1950
|
set: {
|
|
1420
|
-
content
|
|
1951
|
+
content,
|
|
1421
1952
|
sortOrder: order,
|
|
1422
1953
|
updatedAt: now
|
|
1423
1954
|
}
|
|
1424
1955
|
}).returning());
|
|
1956
|
+
const sourcesBefore = existing ? await liveSources(tx, { sectionId: after.id }) : [];
|
|
1957
|
+
const retiredReferences = existing ? await retireRemovedPointers(tx, { sectionId: after.id }, content) : [];
|
|
1958
|
+
const addedSources = input.sources === void 0 ? [] : await addSources(tx, input.projectId, { sectionId: after.id }, content, input.sources, actor);
|
|
1425
1959
|
return {
|
|
1426
|
-
result:
|
|
1960
|
+
result: {
|
|
1961
|
+
...after,
|
|
1962
|
+
referenceChanges: existing ? referenceChanges(existing.content, content, sourcesBefore) : [],
|
|
1963
|
+
addedSources
|
|
1964
|
+
},
|
|
1427
1965
|
event: {
|
|
1428
1966
|
projectId: input.projectId,
|
|
1429
1967
|
entityType: "context_section",
|
|
1430
1968
|
entityId: after.id,
|
|
1431
1969
|
kind: existing ? "updated" : "created",
|
|
1432
1970
|
before: existing ?? void 0,
|
|
1433
|
-
after
|
|
1971
|
+
after: {
|
|
1972
|
+
...after,
|
|
1973
|
+
...retiredReferences.length > 0 ? { retiredReferences } : {},
|
|
1974
|
+
...addedSources.length > 0 ? { addedSources } : {}
|
|
1975
|
+
}
|
|
1434
1976
|
}
|
|
1435
1977
|
};
|
|
1436
1978
|
});
|
|
@@ -1895,20 +2437,27 @@ async function createItem(db, input, actor) {
|
|
|
1895
2437
|
sortPath: path,
|
|
1896
2438
|
parentId,
|
|
1897
2439
|
title: input.title,
|
|
1898
|
-
body: input.body
|
|
2440
|
+
body: input.body === void 0 ? null : bareForm(input.body),
|
|
1899
2441
|
status,
|
|
1900
2442
|
startOn,
|
|
1901
2443
|
dueOn
|
|
1902
2444
|
}).returning());
|
|
1903
2445
|
if (input.deps && input.deps.length > 0) await setDependencies(tx, item, input.deps);
|
|
2446
|
+
const addedSources = input.sources === void 0 ? [] : await addSources(tx, input.projectId, { itemId: item.id }, item.body ?? "", input.sources, actor);
|
|
1904
2447
|
return {
|
|
1905
|
-
result:
|
|
2448
|
+
result: {
|
|
2449
|
+
...item,
|
|
2450
|
+
addedSources
|
|
2451
|
+
},
|
|
1906
2452
|
event: {
|
|
1907
2453
|
projectId: input.projectId,
|
|
1908
2454
|
entityType: "item",
|
|
1909
2455
|
entityId: item.id,
|
|
1910
2456
|
kind: "created",
|
|
1911
|
-
after:
|
|
2457
|
+
after: addedSources.length > 0 ? {
|
|
2458
|
+
...item,
|
|
2459
|
+
addedSources
|
|
2460
|
+
} : item
|
|
1912
2461
|
}
|
|
1913
2462
|
};
|
|
1914
2463
|
});
|
|
@@ -1993,21 +2542,29 @@ async function setStatus(db, args, actor) {
|
|
|
1993
2542
|
* touches it; at least one field must be given. The whole before/after is logged, so the edit is auditable
|
|
1994
2543
|
* and reversible like any other mutation. */
|
|
1995
2544
|
async function editItem(db, input, actor) {
|
|
1996
|
-
if (input.title === void 0 && input.body === void 0 && input.deps === void 0 && input.start === void 0 && input.due === void 0) throw new Error("nothing to edit: provide a title, body, deps, start and/or
|
|
2545
|
+
if (input.title === void 0 && input.body === void 0 && input.deps === void 0 && input.start === void 0 && input.due === void 0 && input.sources === void 0) throw new Error("nothing to edit: provide a title, body, deps, start, due and/or sources");
|
|
1997
2546
|
return mutate(db, actor, async (tx) => {
|
|
1998
2547
|
const before = maybeOne(await tx.select().from(items).where(and(eq(items.projectId, input.projectId), eq(items.ref, input.ref))));
|
|
1999
2548
|
if (before === null) throw new Error(`no ticket "${input.ref}" in this project`);
|
|
2000
2549
|
const changes = { updatedAt: timestamp() };
|
|
2001
2550
|
if (input.title !== void 0) changes.title = input.title;
|
|
2002
|
-
if (input.body !== void 0) changes.body = input.body;
|
|
2551
|
+
if (input.body !== void 0) changes.body = bareForm(input.body);
|
|
2003
2552
|
if (input.start !== void 0) changes.startOn = input.start;
|
|
2004
2553
|
if (input.due !== void 0) changes.dueOn = input.due;
|
|
2005
2554
|
assertDates(input.start === void 0 ? before.startOn : input.start, input.due === void 0 ? before.dueOn : input.due);
|
|
2006
2555
|
const after = one(await tx.update(items).set(changes).where(eq(items.id, before.id)).returning());
|
|
2556
|
+
const sourcesBefore = input.body === void 0 ? [] : await liveSources(tx, { itemId: before.id });
|
|
2557
|
+
const retiredReferences = input.body === void 0 ? [] : await retireRemovedPointers(tx, { itemId: before.id }, after.body ?? "");
|
|
2558
|
+
const addedSources = input.sources === void 0 ? [] : await addSources(tx, input.projectId, { itemId: before.id }, after.body ?? "", input.sources, actor);
|
|
2559
|
+
const changedReferences = input.body === void 0 ? [] : referenceChanges(before.body ?? "", after.body ?? "", sourcesBefore);
|
|
2007
2560
|
const beforeDeps = input.deps === void 0 ? void 0 : await dependencyRefs(tx, before.id);
|
|
2008
2561
|
const afterDeps = input.deps === void 0 ? void 0 : await setDependencies(tx, before, input.deps);
|
|
2009
2562
|
return {
|
|
2010
|
-
result:
|
|
2563
|
+
result: {
|
|
2564
|
+
...after,
|
|
2565
|
+
referenceChanges: changedReferences,
|
|
2566
|
+
addedSources
|
|
2567
|
+
},
|
|
2011
2568
|
event: {
|
|
2012
2569
|
projectId: input.projectId,
|
|
2013
2570
|
entityType: "item",
|
|
@@ -2019,7 +2576,9 @@ async function editItem(db, input, actor) {
|
|
|
2019
2576
|
},
|
|
2020
2577
|
after: {
|
|
2021
2578
|
...after,
|
|
2022
|
-
deps: afterDeps
|
|
2579
|
+
deps: afterDeps,
|
|
2580
|
+
...retiredReferences.length > 0 ? { retiredReferences } : {},
|
|
2581
|
+
...addedSources.length > 0 ? { addedSources } : {}
|
|
2023
2582
|
}
|
|
2024
2583
|
}
|
|
2025
2584
|
};
|