Pick any line to see why it is the way it is: the commit, the pull request and issue it came from, and what the agent was thinking.
| Docs know what code they describe; a project's docs folder in Docs; Docs events; files on any S3 store | 1 | import assert from "node:assert/strict"; |
| 2 | import { test } from "node:test"; | |
| 3 | ||
| 4 | import { bodyCitations, citationHref, citationMarkdown, citationsFromMarkdown, cleanCitation, cleanDescribes, cleanPath, touchedPaths, touches } from "./citations.ts"; | |
| 5 | ||
| 6 | test("paths are kept tidy, and unsafe ones refused", () => { | |
| 7 | assert.equal(cleanPath("/src//export.ts/"), "src/export.ts"); | |
| 8 | assert.equal(cleanPath("./docs/a.md"), "docs/a.md"); | |
| 9 | assert.equal(cleanPath("src/../secrets"), null); | |
| 10 | assert.equal(cleanPath(""), null); | |
| 11 | }); | |
| 12 | ||
| 13 | test("a citation names a repository and a path; a label only for what it names", () => { | |
| 14 | assert.deepEqual(cleanCitation({ repo: "Acme/Web", path: "src/export.ts", kind: "symbol", label: " exportCsv ", ref: "ABCDEF1" }, "body"), { | |
| 15 | repo: "acme/web", | |
| 16 | path: "src/export.ts", | |
| 17 | kind: "symbol", | |
| 18 | label: "exportCsv", | |
| 19 | ref: "abcdef1", | |
| 20 | source: "body", | |
| 21 | }); | |
| 22 | assert.equal(cleanCitation({ repo: "acme/web", path: "src/a.ts", kind: "path", label: "ignored" }, "body")?.label, null); | |
| 23 | assert.equal(cleanCitation({ repo: "nope", path: "src/a.ts" }, "body"), null); | |
| 24 | assert.equal(cleanCitation({ repo: "acme/web", path: "src/a.ts", kind: "weird" as never }, "body")?.kind, "path"); | |
| 25 | }); | |
| 26 | ||
| 27 | test("a change touches a cited file, anything under a cited folder, and what a glob matches", () => { | |
| 28 | assert.ok(touches("src/export.ts", "src/export.ts")); | |
| 29 | assert.ok(!touches("src/export.ts", "src/export.tsx")); | |
| 30 | assert.ok(touches("src/export", "src/export/csv.ts")); | |
| 31 | assert.ok(!touches("src/export", "src/exports/csv.ts")); | |
| 32 | assert.ok(touches("src/*.ts", "src/a.ts")); | |
| 33 | assert.ok(!touches("src/*.ts", "src/deep/a.ts")); | |
| 34 | assert.ok(touches("src/**/*.sql", "src/a.sql")); | |
| 35 | assert.ok(touches("src/**/*.sql", "src/db/migrations/0001.sql")); | |
| 36 | assert.ok(touches("api/**", "api/v1/routes.rs")); | |
| 37 | assert.ok(touches("docs/?.md", "docs/a.md")); | |
| 38 | assert.ok(!touches("docs/?.md", "docs/ab.md")); | |
| 39 | assert.ok(!touches("a.b/*.ts", "aXb/x.ts")); | |
| 40 | assert.deepEqual(touchedPaths([{ path: "src/export" }, { path: "*.toml" }], ["README.md", "src/export/csv.ts", "Cargo.toml"]), ["src/export/csv.ts", "Cargo.toml"]); | |
| 41 | }); | |
| 42 | ||
| 43 | test("a citation links to the code at the commit it was cited at", () => { | |
| 44 | assert.equal(citationHref({ repo: "acme/web", path: "src/export.ts", ref: "abc1234" }), "/acme/web/blob/abc1234/src/export.ts"); | |
| 45 | assert.equal(citationHref({ repo: "acme/web", path: "src/export", ref: null }), "/acme/web/tree/HEAD/src/export"); | |
| 46 | assert.equal(citationHref({ repo: "acme/web", path: "src/**/*.sql", ref: null }), "/acme/web/tree/HEAD/src"); | |
| 47 | assert.equal(citationMarkdown({ repo: "acme/web", path: "src/export.ts", ref: "abc1234", kind: "env", label: "EXPORT_BUCKET" }), "[`EXPORT_BUCKET`](/acme/web/blob/abc1234/src/export.ts)"); | |
| 48 | }); | |
| 49 | ||
| 50 | test("links to code in a page are citations too, a chip's own link once", () => { | |
| 51 | const md = "See [`exportCsv`](/acme/web/blob/abc1234/src/export.ts) and [the folder](/acme/web/tree/main/src/jobs) and [elsewhere](https://example.com/a/b/blob/x/y.ts) and [on g1t](https://g1t.sh/acme/api/blob/main/src/lib.rs#L10)."; | |
| 52 | assert.deepEqual( | |
| 53 | citationsFromMarkdown(md).map((c) => [c.repo, c.path, c.ref]), | |
| 54 | [ | |
| 55 | ["acme/web", "src/export.ts", "abc1234"], | |
| 56 | ["acme/web", "src/jobs", "main"], | |
| 57 | ["acme/api", "src/lib.rs", "main"], | |
| 58 | ], | |
| 59 | ); | |
| 60 | const chips = [{ repo: "acme/web", path: "src/export.ts", kind: "symbol" as const, label: "exportCsv", ref: "abc1234" }]; | |
| 61 | const all = bodyCitations(chips, md); | |
| 62 | assert.deepEqual( | |
| 63 | all.map((c) => [c.path, c.kind]), | |
| 64 | [ | |
| 65 | ["src/export.ts", "symbol"], | |
| 66 | ["src/jobs", "path"], | |
| 67 | ["src/lib.rs", "path"], | |
| 68 | ], | |
| 69 | ); | |
| 70 | }); | |
| 71 | ||
| 72 | test("the header's Describes list is tidy and short", () => { | |
| 73 | assert.deepEqual(cleanDescribes([{ repo: "Acme/Web", path: "/src/export/" }, { repo: "acme/web", path: "src/export" }, { repo: "x", path: "y" }, "nope"]), [{ repo: "acme/web", path: "src/export" }]); | |
| 74 | assert.equal(cleanDescribes(Array.from({ length: 40 }, (_, i) => ({ repo: "acme/web", path: `f${i}` }))).length, 20); | |
| 75 | }); |
