vowel 0.6.3 → 0.7.0-beta.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.
Files changed (165) hide show
  1. package/README.md +23 -17
  2. package/bin.js +87 -30
  3. package/cli.js +15 -0
  4. package/config.js +102 -16
  5. package/extractDate.js +70 -6
  6. package/index.js +14 -5
  7. package/package.json +42 -7
  8. package/plugins/assets/index.js +65 -0
  9. package/plugins/atproto/index.js +132 -0
  10. package/plugins/atproto/password.js +71 -0
  11. package/plugins/atproto/publish.js +406 -0
  12. package/plugins/atproto/record.js +144 -0
  13. package/plugins/atproto/rkey.js +54 -0
  14. package/plugins/deploy-cloudflare/index.js +92 -0
  15. package/plugins/fonts/index.js +18 -21
  16. package/plugins/html/assets/bundle-BeK1Hptv.css +21 -0
  17. package/plugins/html/bundle/assets/index-BeK1Hptv.css +21 -0
  18. package/plugins/html/bundle/index.js +21145 -0
  19. package/plugins/html/editor/EditButton.svelte +152 -0
  20. package/plugins/html/editor/Editor.svelte +51 -0
  21. package/plugins/html/editor/Overlays.svelte +6 -0
  22. package/plugins/html/editor/SettingsPanel.svelte +397 -0
  23. package/plugins/html/editor/Toolbar.svelte +644 -0
  24. package/plugins/html/editor/create-session.js +250 -0
  25. package/plugins/html/editor/directives.js +128 -0
  26. package/plugins/html/editor/frontmatter.js +97 -0
  27. package/plugins/html/editor/ingest.js +339 -0
  28. package/plugins/html/editor/main.js +94 -0
  29. package/plugins/html/editor/nodes/Alert.svelte +21 -0
  30. package/plugins/html/editor/nodes/Blockquote.svelte +9 -0
  31. package/plugins/html/editor/nodes/CodeBlock.svelte +19 -0
  32. package/plugins/html/editor/nodes/Embed.svelte +19 -0
  33. package/plugins/html/editor/nodes/Emphasis.svelte +11 -0
  34. package/plugins/html/editor/nodes/Heading.svelte +15 -0
  35. package/plugins/html/editor/nodes/Highlight.svelte +11 -0
  36. package/plugins/html/editor/nodes/Image.svelte +18 -0
  37. package/plugins/html/editor/nodes/InlineCode.svelte +11 -0
  38. package/plugins/html/editor/nodes/Link.svelte +17 -0
  39. package/plugins/html/editor/nodes/List.svelte +15 -0
  40. package/plugins/html/editor/nodes/ListItem.svelte +9 -0
  41. package/plugins/html/editor/nodes/Page.svelte +21 -0
  42. package/plugins/html/editor/nodes/Paragraph.svelte +9 -0
  43. package/plugins/html/editor/nodes/Strikethrough.svelte +11 -0
  44. package/plugins/html/editor/nodes/Strong.svelte +11 -0
  45. package/plugins/html/editor/nodes/ThematicBreak.svelte +9 -0
  46. package/plugins/html/editor/nodes/index.js +18 -0
  47. package/plugins/html/editor/rollup.config.js +35 -0
  48. package/plugins/html/editor/serialize.js +157 -0
  49. package/plugins/html/editor/settings-file.js +83 -0
  50. package/plugins/html/editor/socket.js +202 -0
  51. package/plugins/html/editor/source.js +43 -0
  52. package/plugins/html/image.js +104 -0
  53. package/plugins/html/index.js +760 -0
  54. package/plugins/html/partials.js +299 -0
  55. package/plugins/html/socialLinks.js +67 -0
  56. package/plugins/html/writeRules.js +377 -0
  57. package/plugins/icons/index.js +2 -6
  58. package/plugins/images/index.js +78 -55
  59. package/plugins/markdown/brandColors.js +10 -0
  60. package/plugins/markdown/colorScheme.js +64 -0
  61. package/plugins/markdown/emoji.js +30 -0
  62. package/plugins/markdown/frontmatter.js +253 -0
  63. package/plugins/markdown/index.js +287 -1274
  64. package/plugins/markdown/links.js +97 -0
  65. package/plugins/markdown/metadata.js +308 -0
  66. package/plugins/markdown/readRules.js +143 -0
  67. package/plugins/markdown/typography.js +109 -0
  68. package/plugins/markdown/visitor.js +143 -0
  69. package/plugins/publish/index.js +34 -0
  70. package/plugins/robots/agents.js +79 -0
  71. package/plugins/robots/index.js +30 -10
  72. package/plugins/robots/robots.js +48 -0
  73. package/plugins/styles/index.js +111 -26
  74. package/plugins/styles/theme.js +116 -0
  75. package/plugins/urls/index.js +78 -0
  76. package/plugins/urls/urlMetadata.js +246 -0
  77. package/plugins/vectors/index.js +5 -9
  78. package/plugins/xml/entryContent.js +103 -0
  79. package/plugins/xml/index.js +123 -50
  80. package/secretPaths.js +170 -0
  81. package/stylesheets/DefaultStyles.css +367 -437
  82. package/stylesheets/ResetStyles.css +2 -38
  83. package/stylesheets/SyntaxHighlightingStyles.css +269 -0
  84. package/stylesheets/TypographyStyles.css +386 -128
  85. package/systemPaths.js +48 -0
  86. package/utils.js +56 -5
  87. package/.github/ISSUE_TEMPLATE/bug_report.md +0 -73
  88. package/.github/ISSUE_TEMPLATE/config.yml +0 -7
  89. package/docs-source/.cache.json +0 -9
  90. package/docs-source/.obsidian/app.json +0 -3
  91. package/docs-source/.obsidian/appearance.json +0 -3
  92. package/docs-source/.obsidian/core-plugins-migration.json +0 -30
  93. package/docs-source/.obsidian/core-plugins.json +0 -20
  94. package/docs-source/.obsidian/workspace.json +0 -168
  95. package/docs-source/.stackblitzrc +0 -3
  96. package/docs-source/.votive.db +0 -0
  97. package/docs-source/about.md +0 -3
  98. package/docs-source/blog/home.md +0 -5
  99. package/docs-source/blog/url-ui.md +0 -21
  100. package/docs-source/blog.md +0 -5
  101. package/docs-source/docs/.votive.db +0 -0
  102. package/docs-source/docs/deploy.md +0 -67
  103. package/docs-source/docs/file-structure.md +0 -31
  104. package/docs-source/docs/folder-settings.md +0 -23
  105. package/docs-source/docs/home.md +0 -55
  106. package/docs-source/docs/images.md +0 -10
  107. package/docs-source/docs/items.md +0 -13
  108. package/docs-source/docs/pages.md +0 -141
  109. package/docs-source/docs/settings.md +0 -4
  110. package/docs-source/docs/styling.md +0 -34
  111. package/docs-source/docs/taxonomies.md +0 -37
  112. package/docs-source/features/cards.md +0 -7
  113. package/docs-source/features/editing.md +0 -7
  114. package/docs-source/features/emoji.md +0 -7
  115. package/docs-source/features/frontmatter.md +0 -7
  116. package/docs-source/features/lists.md +0 -7
  117. package/docs-source/features/navigation.md +0 -7
  118. package/docs-source/features/rich-previews.md +0 -7
  119. package/docs-source/features/robots.md +0 -7
  120. package/docs-source/features/rss.md +0 -7
  121. package/docs-source/features/sitemap.md +0 -7
  122. package/docs-source/features/speed.md +0 -7
  123. package/docs-source/features/static.md +0 -7
  124. package/docs-source/features/taxonomies.md +0 -7
  125. package/docs-source/home.md +0 -42
  126. package/docs-source/output/about.html +0 -1
  127. package/docs-source/output/blog/url-ui.html +0 -8
  128. package/docs-source/output/blog.html +0 -1
  129. package/docs-source/output/default.css +0 -1
  130. package/docs-source/output/docs/deploy.html +0 -34
  131. package/docs-source/output/docs/file-structure.html +0 -24
  132. package/docs-source/output/docs/folder-settings.html +0 -20
  133. package/docs-source/output/docs/images.html +0 -2
  134. package/docs-source/output/docs/items.html +0 -6
  135. package/docs-source/output/docs/pages.html +0 -101
  136. package/docs-source/output/docs/styling.html +0 -18
  137. package/docs-source/output/docs/taxonomies.html +0 -20
  138. package/docs-source/output/docs.html +0 -28
  139. package/docs-source/output/features/cards.html +0 -1
  140. package/docs-source/output/features/editing.html +0 -1
  141. package/docs-source/output/features/emoji.html +0 -1
  142. package/docs-source/output/features/frontmatter.html +0 -1
  143. package/docs-source/output/features/lists.html +0 -1
  144. package/docs-source/output/features/navigation.html +0 -1
  145. package/docs-source/output/features/rich-previews.html +0 -1
  146. package/docs-source/output/features/robots.html +0 -1
  147. package/docs-source/output/features/rss.html +0 -1
  148. package/docs-source/output/features/sitemap.html +0 -1
  149. package/docs-source/output/features/speed.html +0 -1
  150. package/docs-source/output/features/static.html +0 -1
  151. package/docs-source/output/features/taxonomies.html +0 -1
  152. package/docs-source/output/features.html +0 -1
  153. package/docs-source/output/feed.xml +0 -1
  154. package/docs-source/output/index.html +0 -21
  155. package/docs-source/output/reset.css +0 -1
  156. package/docs-source/output/roadmap.html +0 -87
  157. package/docs-source/output/robots.txt +0 -14
  158. package/docs-source/output/sitemap.xml +0 -16
  159. package/docs-source/output/typography.css +0 -1
  160. package/docs-source/roadmap.md +0 -98
  161. package/docs-source/settings.md +0 -13
  162. package/getMetadata.js +0 -41
  163. package/jsconfig.json +0 -10
  164. package/regex.js +0 -36
  165. package/stylesheets/brand-colors.css +0 -119
@@ -0,0 +1,143 @@
1
+ /**
2
+ * One walk for every text-level utility. Rules are data; this is the
3
+ * only traversal. Tree-agnostic: mdast at read, hast at transform and
4
+ * write - both are `{type, children}` trees with `{type: "text", value}`
5
+ * leaves, and a rule knows which one it is written for.
6
+ *
7
+ * Per node, in order: the block rules (first match wins, and what it
8
+ * returns decides whether the walk descends); then `skip`, which keeps
9
+ * inline rules out of code; then, for a text node, every inline rule in
10
+ * one scan - the earliest match wins, ties go to rule order, `resolve()`
11
+ * returning null leaves the text as written. The pieces replace the node
12
+ * and the walk continues *after* them, so a rule never sees its own
13
+ * output.
14
+ *
15
+ * Kept free of node builtins: the same rules could run in the browser.
16
+ *
17
+ * @typedef {{ type: string, value?: string, children?: Node[], [key: string]: any }} Node
18
+ *
19
+ * @typedef {object} InlineRule
20
+ * @property {string} name
21
+ * @property {RegExp} pattern - flags are ignored; the visitor scans with
22
+ * its own global copy
23
+ * @property {(match: RegExpExecArray, context: any) => Node | Node[] | null} resolve
24
+ *
25
+ * @typedef {object} BlockRule
26
+ * @property {string} name
27
+ * @property {(node: Node, index: number, parent: Node) => boolean} test
28
+ * @property {(node: Node, index: number, parent: Node, context: any) => Node | Node[] | typeof SKIP | undefined} transform
29
+ * `undefined`: mutated in place, descended into. A node or array:
30
+ * spliced in, not descended into - the rule made it. `SKIP`: left
31
+ * alone, not descended into.
32
+ */
33
+
34
+ const SKIP = Symbol("skip")
35
+
36
+ /**
37
+ * @param {object} rules
38
+ * @param {InlineRule[]} [rules.inline]
39
+ * @param {BlockRule[]} [rules.block]
40
+ * @param {(node: Node) => boolean} [rules.skip] - not descended into
41
+ * @returns {(tree: Node, context?: any) => void}
42
+ */
43
+ function createVisitor({ inline = [], block = [], skip = () => false } = {}) {
44
+ const scanners = inline.map(rule => ({ rule, pattern: new RegExp(rule.pattern.source, "g") }))
45
+
46
+ /**
47
+ * Text into the pieces the inline rules make of it. Returns null when
48
+ * no rule matched, so an untouched node is left in place unchanged.
49
+ * @param {string} value
50
+ * @param {any} context
51
+ * @returns {Node[] | null}
52
+ */
53
+ function applyInline(value, context) {
54
+ const pieces = []
55
+ let cursor = 0
56
+ let touched = false
57
+
58
+ while (cursor < value.length) {
59
+ const earliest = scanners.reduce((best, scanner) => {
60
+ scanner.pattern.lastIndex = cursor
61
+ const match = scanner.pattern.exec(value)
62
+ if (!match || match[0].length === 0) return best
63
+ if (best && best.match.index <= match.index) return best
64
+ return { match, rule: scanner.rule }
65
+ }, /** @type {{match: RegExpExecArray, rule: InlineRule} | null} */ (null))
66
+
67
+ if (!earliest) break
68
+
69
+ const { match, rule } = earliest
70
+ const resolved = rule.resolve(match, context)
71
+ const end = match.index + match[0].length
72
+
73
+ if (resolved === null || resolved === undefined) {
74
+ // Literal: keep scanning after it, as part of the same text run.
75
+ cursor = end
76
+ continue
77
+ }
78
+
79
+ touched = true
80
+ const before = value.slice(pieces.length ? pieces.at(-1).end : 0, match.index)
81
+ if (before) pieces.push({ end: match.index, nodes: [{ type: "text", value: before }] })
82
+ pieces.push({ end, nodes: Array.isArray(resolved) ? resolved : [resolved] })
83
+ cursor = end
84
+ }
85
+
86
+ if (!touched) return null
87
+
88
+ const tail = value.slice(pieces.at(-1).end)
89
+ const nodes = pieces.flatMap(piece => piece.nodes)
90
+ return tail ? [...nodes, { type: "text", value: tail }] : nodes
91
+ }
92
+
93
+ /**
94
+ * @param {Node} node
95
+ * @param {number} index
96
+ * @param {Node} parent
97
+ * @param {any} context
98
+ * @returns {number} how many nodes now occupy the slot, for the caller
99
+ * to step over
100
+ */
101
+ function visitNode(node, index, parent, context) {
102
+ const matched = block.find(rule => rule.test(node, index, parent))
103
+ if (matched) {
104
+ const result = matched.transform(node, index, parent, context)
105
+ if (result === SKIP) return 1
106
+ if (result !== undefined) {
107
+ const nodes = Array.isArray(result) ? result : [result]
108
+ parent.children.splice(index, 1, ...nodes)
109
+ return nodes.length
110
+ }
111
+ }
112
+
113
+ if (skip(node)) return 1
114
+
115
+ if (node.type === "text" && typeof node.value === "string") {
116
+ const pieces = applyInline(node.value, context)
117
+ if (!pieces) return 1
118
+ parent.children.splice(index, 1, ...pieces)
119
+ return pieces.length
120
+ }
121
+
122
+ visitChildren(node, context)
123
+ return 1
124
+ }
125
+
126
+ /**
127
+ * @param {Node} node
128
+ * @param {any} context
129
+ */
130
+ function visitChildren(node, context) {
131
+ if (!Array.isArray(node.children)) return
132
+ let index = 0
133
+ while (index < node.children.length) {
134
+ index += visitNode(node.children[index], index, node, context)
135
+ }
136
+ }
137
+
138
+ return function walk(tree, context = {}) {
139
+ visitChildren(tree, context)
140
+ }
141
+ }
142
+
143
+ export { createVisitor, SKIP }
@@ -0,0 +1,34 @@
1
+ import { deployToCloudflarePages } from "../deploy-cloudflare/index.js"
2
+ import { publishToAtproto } from "../atproto/publish.js"
3
+
4
+ /**
5
+ * `vowel --command publish`: the site to Cloudflare Pages, then its
6
+ * records to AT Protocol, in that order - the pages and the well-known
7
+ * files are live before any record points at them. A failed deploy stops
8
+ * it there. A site with no `atproto_did` is deployed and nothing more.
9
+ *
10
+ * The payload is passed to both: `{"dryRun": true}` builds, reports what
11
+ * each would do and sends nothing; `{"projectName": "…"}` overrides
12
+ * `cloudflare_project`.
13
+ *
14
+ * @param {{ dryRun?: boolean, projectName?: string } | undefined} payload
15
+ * @param {{ config: import("votive").VotiveConfig, notify: (message: object) => void }} context
16
+ */
17
+ async function publish(payload, context) {
18
+ const cloudflare = await deployToCloudflarePages(payload, context)
19
+ const atproto = await publishToAtproto({ ...payload, optional: true }, context)
20
+ return { cloudflare, atproto }
21
+ }
22
+
23
+ /**
24
+ * In vowel's default plugin list (config.js), beside the two commands it
25
+ * runs.
26
+ * @type {import("votive").VotivePlugin}
27
+ */
28
+ const vowelPublishPlugin = {
29
+ name: "vowel-publish",
30
+ commands: { publish }
31
+ }
32
+
33
+ export default vowelPublishPlugin
34
+ export { publish }
@@ -0,0 +1,79 @@
1
+ /**
2
+ * Crawler groups an author can toggle from settings.md:
3
+ *
4
+ * robots:
5
+ * ai: false # every agent in the ai group: Disallow: /
6
+ * images: false
7
+ * search: true
8
+ * all: true # the `*` agent
9
+ * GPTBot: true # one agent, overriding its group
10
+ *
11
+ * The AI list is the catch-all Sam asked for: it is long and it grows,
12
+ * and nobody wants to maintain it in every settings.md. Names are the
13
+ * agents' own spellings (robots.txt matching is case-insensitive, but
14
+ * the file reads better with the real ones). Free of node builtins so a
15
+ * settings panel can import it.
16
+ */
17
+ const groups = {
18
+ ai: [
19
+ "GPTBot",
20
+ "ChatGPT-User",
21
+ "OAI-SearchBot",
22
+ "ClaudeBot",
23
+ "Claude-Web",
24
+ "anthropic-ai",
25
+ "Google-Extended",
26
+ "Applebot-Extended",
27
+ "CCBot",
28
+ "Bytespider",
29
+ "PerplexityBot",
30
+ "Perplexity-User",
31
+ "Amazonbot",
32
+ "FacebookBot",
33
+ "Meta-ExternalAgent",
34
+ "Meta-ExternalFetcher",
35
+ "cohere-ai",
36
+ "Diffbot",
37
+ "omgili",
38
+ "omgilibot",
39
+ "YouBot",
40
+ "ImagesiftBot",
41
+ "Timpibot",
42
+ "PetalBot",
43
+ "Kangaroo Bot",
44
+ "AI2Bot",
45
+ "Ai2Bot-Dolma",
46
+ "DuckAssistBot",
47
+ "MistralAI-User",
48
+ "iaskspider/2.0",
49
+ "ICC-Crawler",
50
+ "img2dataset",
51
+ "Webzio-Extended",
52
+ "Scrapy"
53
+ ],
54
+ images: [
55
+ "Googlebot-Image",
56
+ "msnbot-media",
57
+ "Baiduspider-image",
58
+ "YandexImages"
59
+ ],
60
+ search: [
61
+ "Googlebot",
62
+ "Bingbot",
63
+ "DuckDuckBot",
64
+ "Baiduspider",
65
+ "YandexBot",
66
+ "Applebot",
67
+ "Slurp"
68
+ ],
69
+ all: ["*"]
70
+ }
71
+
72
+ /**
73
+ * What a settings.md that says nothing gets: AI training and image
74
+ * crawlers kept out, search left alone. This is the file vowel wrote
75
+ * before the setting existed, with the AI list filled in.
76
+ */
77
+ const defaults = { ai: false, images: false }
78
+
79
+ export { groups, defaults }
@@ -1,23 +1,43 @@
1
- /** @import * as Votive from "votive" */
2
-
1
+ import generateRobots from "./robots.js"
3
2
 
3
+ /** @import * as Votive from "votive" */
4
4
 
5
- /** @type {Votive.VotiveProcessor} */
5
+ /**
6
+ * `robots.txt` is a stub: vowel declares it unconditionally and an author
7
+ * who writes their own `robots.txt` shadows it, which is the whole of the
8
+ * override rule. It used to be created from the markdown plugin's
9
+ * readFolder, which is why generateRobots lived over there.
10
+ *
11
+ * Configured from the root settings.md's `robots` setting (see
12
+ * agents.js for the groups), and it names the sitemap when `domain` is
13
+ * set. Both ride in the stub's params, so a change to either re-expands
14
+ * the file and nothing else does. The default list still has no
15
+ * version stamp: see tasks/1-proposed/wipe-cache-on-upgrade.md.
16
+ *
17
+ * @type {Votive.VotiveProcessor}
18
+ */
6
19
  const processor = {
7
20
  extensions: [".txt"],
8
21
  format: "text",
9
- writeFile: (target) => ({ data: target.abstract.content })
22
+ createStubs: ({ settings }) => [{
23
+ path: "robots.txt",
24
+ params: {
25
+ robots: settings.lastNonNull("fm_robots") ?? null,
26
+ domain: settings.lastNonNull("fm_domain") ?? null
27
+ }
28
+ }],
29
+ expandStubs: ({ params }) => ({ text: generateRobots(params.robots ?? {}, params.domain ?? undefined) }),
30
+ // A .txt source carries no metadata worth inferring; its text is the
31
+ // target's content and the write pass hands it straight back.
32
+ readFile: (source) => ({ data: source.text, metadata: {} }),
33
+ writeFile: (target) => ({ data: target.data }),
34
+ router: ({ name, dir, ext }) => ({ name, dir, ext })
10
35
  }
11
36
 
12
37
  /** @type {Votive.VotivePlugin} */
13
38
  const plugin = {
14
39
  name: "vowel-robots",
15
- processors: [processor],
16
- router: ({ name, dir, ext }) => {
17
- return {
18
- name, dir, ext
19
- }
20
- }
40
+ processors: [processor]
21
41
  }
22
42
 
23
43
  export default plugin
@@ -0,0 +1,48 @@
1
+ import { groups, defaults } from "./agents.js"
2
+
3
+ /**
4
+ * The robots.txt text for a `robots` setting. Group keys expand to every
5
+ * agent in the group; any other key is an agent name and overrides its
6
+ * group. `true` is `Allow: /`, `false` is `Disallow: /`, anything else
7
+ * is ignored. Agents nobody mentioned get no block, which robots.txt
8
+ * reads as allowed.
9
+ *
10
+ * Order in the file: `*` last, because a crawler takes the most specific
11
+ * matching group and a reader scanning the file expects the catch-all
12
+ * at the bottom.
13
+ * @param {Record<string, unknown>} [config] - the `robots` setting
14
+ * @param {string} [domain] - emits the Sitemap line when set
15
+ */
16
+ function generateRobots(config = {}, domain) {
17
+ // Only booleans are opinions; anything else leaves the default in place.
18
+ const declared = Object.entries(config).filter(([, value]) => typeof value === "boolean")
19
+ const settings = { ...defaults, ...Object.fromEntries(declared) }
20
+ const groupNames = Object.keys(groups)
21
+ const lower = (name) => String(name).toLowerCase()
22
+
23
+ // Group rules first, then per-agent overrides on top. The map is keyed
24
+ // by lowercase name so `gptbot: true` overrides `GPTBot` in the ai
25
+ // group; the group's own spelling is what gets written.
26
+ const spelling = new Map(Object.values(groups).flat().map(agent => [lower(agent), agent]))
27
+ const rules = new Map()
28
+
29
+ for (const [key, value] of Object.entries(settings)) {
30
+ if (!groupNames.includes(lower(key))) continue
31
+ for (const agent of groups[lower(key)]) rules.set(lower(agent), value)
32
+ }
33
+ for (const [key, value] of Object.entries(settings)) {
34
+ if (groupNames.includes(lower(key))) continue
35
+ rules.set(lower(key), value)
36
+ if (!spelling.has(lower(key))) spelling.set(lower(key), key)
37
+ }
38
+
39
+ const blocks = [...rules.entries()]
40
+ .sort(([a], [b]) => (a === "*") - (b === "*"))
41
+ .map(([agent, allowed]) => `User-agent: ${spelling.get(agent)}\n${allowed ? "Allow" : "Disallow"}: /`)
42
+
43
+ const sitemap = domain ? [`Sitemap: https://${domain}/sitemap.xml`] : []
44
+
45
+ return [...blocks, ...sitemap].join("\n\n")
46
+ }
47
+
48
+ export default generateRobots
@@ -1,13 +1,103 @@
1
1
  import path from "node:path"
2
+ import { readFileSync } from "node:fs"
3
+ import { styleText } from "node:util"
2
4
  import { transform } from "lightningcss"
5
+ import { hash } from "node:crypto"
6
+ import { resolveTheme, themeStylesheets, themeKey } from "./theme.js"
7
+ import { themeColorSchemeCSS } from "../markdown/colorScheme.js"
8
+ import { typographyCSS } from "../markdown/typography.js"
3
9
 
4
10
  /** @import * as Votive from "votive" */
5
11
 
12
+ const VOWEL_DIR = path.normalize(path.join(import.meta.dirname, "../../"))
13
+
14
+ /** Vowel's own bundled stylesheets, by target path. */
15
+ const BUNDLED = {
16
+ "reset.css": "ResetStyles.css",
17
+ "typography.css": "TypographyStyles.css",
18
+ "default.css": "DefaultStyles.css",
19
+ "syntax-highlighting.css": "SyntaxHighlightingStyles.css"
20
+ }
21
+
22
+ /**
23
+ * The stylesheets vowel generates, as stubs.
24
+ *
25
+ * These used to be created from the markdown plugin's readFolder, which
26
+ * reran for every folder on every pass and re-created each sheet with its
27
+ * raw text - fighting the write pass, which stores back the minified
28
+ * output. That flip is what made every page's cache-buster change twice a
29
+ * build (see tasks/3-in-review/stylesheet-data-flip-flop.md). A stub is
30
+ * expanded only when its params change, so nothing re-creates them and
31
+ * `data` settles.
32
+ *
33
+ * A bundled sheet carries no params: its content is part of the software,
34
+ * not the project. That means a warm database never re-reads it, which is
35
+ * fine while the CLI wipes on every launch and is why the version stamp
36
+ * in tasks/1-proposed/post-stubs-vowel-followups.md is parked rather than
37
+ * forgotten.
38
+ *
39
+ * @type {Votive.ProcessorStubs}
40
+ */
41
+ function createStubs({ api, settings }) {
42
+ // Every theme any folder declares, plus the root's resolved one (which
43
+ // is the default when nothing declares it), one set of generated sheets
44
+ // each. The `settings` handed here is the root's view; settingValues
45
+ // is how the enumerator sees what subfolders declared.
46
+ const rootTheme = settings.lastNonNull("theme")
47
+ const declared = api.settingValues("theme")
48
+ const themes = [rootTheme, ...declared].filter((theme, index, all) => (
49
+ all.findIndex(other => themeKey(other) === themeKey(theme)) === index
50
+ ))
51
+
52
+ const sheets = themes.flatMap(theme => {
53
+ const { config } = resolveTheme(theme)
54
+ return themeStylesheets(theme, rootTheme).map(sheet => {
55
+ // Generated sheets carry the part of the theme they are generated
56
+ // from, so they re-expand exactly when that part changes.
57
+ if (sheet.startsWith("colors")) return { path: sheet, params: { colors: config.colors ?? null } }
58
+ if (sheet.startsWith("type")) return { path: sheet, params: { theme: config } }
59
+ return { path: sheet }
60
+ })
61
+ }).filter((sheet, index, all) => all.findIndex(other => other.path === sheet.path) === index)
62
+
63
+ // Always declared, unlike the rest: it was created from the html
64
+ // writeFile the first time a page happened to contain a code block,
65
+ // which made its existence depend on the order pages were written in.
66
+ // Pages still link it only when they have code.
67
+ return [...sheets, { path: "syntax-highlighting.css" }]
68
+ }
69
+
70
+ /**
71
+ * @type {Votive.ProcessorExpand}
72
+ */
73
+ function expandStubs({ path: sourcePath, params }) {
74
+ const bundled = BUNDLED[sourcePath]
75
+ if (bundled) {
76
+ return { text: readFileSync(path.join(VOWEL_DIR, "stylesheets", bundled), "utf-8") }
77
+ }
78
+
79
+ if (/^colors(-[0-9a-f]{8})?\.css$/.test(sourcePath)) {
80
+ // Reports and falls back rather than throwing: a site with unusable
81
+ // colours should lose its palette, not its build.
82
+ return {
83
+ text: themeColorSchemeCSS(params?.colors, error => (
84
+ console.warn(`${styleText("dim", "build: ")}${styleText("yellow", `ignoring theme.colors - ${error.message}`)}`)
85
+ ))
86
+ }
87
+ }
88
+
89
+ if (/^type(-[0-9a-f]{8})?\.css$/.test(sourcePath)) {
90
+ return { text: typographyCSS(params?.theme)?.css ?? "" }
91
+ }
92
+
93
+ return null
94
+ }
95
+
6
96
  /** @type {Votive.ProcessorWrite} */
7
- function writeCSS(destination, database, config) {
97
+ function writeCSS(target, { config }) {
8
98
  const { code, map } = transform({
9
- filename: destination.path,
10
- code: Buffer.from(destination.abstract.css),
99
+ filename: target.path,
100
+ code: Buffer.from(target.data ?? ""),
11
101
  minify: true,
12
102
  targets: {
13
103
  chrome: 140 << 16,
@@ -26,24 +116,21 @@ function writeCSS(destination, database, config) {
26
116
 
27
117
 
28
118
 
29
- /** @type {Votive.ReadText} */
30
- function readCSS(text, filePath, destinationPath, database, config) {
31
- const pathInfo = path.parse(filePath)
32
-
33
- database.setting.create(
34
- pathInfo.dir,
35
- "stylesheets",
36
- filePath
37
- )
38
-
39
- const metadata = {}
40
- const abstract = {
41
- css: text
42
- }
43
-
119
+ /** @type {Votive.ProcessorRead} */
120
+ function readCSS(source) {
44
121
  return {
45
- metadata,
46
- abstract
122
+ metadata: { hash: hash("MD5", source.text).slice(0, 8) },
123
+ // The CSS itself is the target's content. After the first write pass
124
+ // `data` holds the minified output instead - transform() is idempotent
125
+ // over its own output, so a later rewrite produces the same bytes.
126
+ //
127
+ // No `settings` contribution. "Which stylesheets apply to a folder"
128
+ // is a listing, not a setting: the html plugin asks api.targets()
129
+ // for the .css targets in each of a page's ancestor folders. This
130
+ // used to push `stylesheets: [source.path]` into the same label the
131
+ // theme's built-ins are written under, which is what needed a
132
+ // multi-writer accumulator behind every settings row.
133
+ data: source.text
47
134
  }
48
135
  }
49
136
 
@@ -51,6 +138,9 @@ function readCSS(text, filePath, destinationPath, database, config) {
51
138
  const cssWriter = {
52
139
  extensions: [".css"],
53
140
  format: "text",
141
+ router: ({ name, dir, ext }) => ({ name, dir, ext }),
142
+ createStubs,
143
+ expandStubs,
54
144
  readFile: readCSS,
55
145
  writeFile: writeCSS
56
146
  }
@@ -58,12 +148,7 @@ const cssWriter = {
58
148
  /** @type {Votive.VotivePlugin} */
59
149
  const vowelStylesPlugin = {
60
150
  name: "vowel-styles",
61
- processors: [cssWriter],
62
- router: ({ name, dir, ext }) => {
63
- return {
64
- name, dir, ext
65
- }
66
- }
151
+ processors: [cssWriter]
67
152
  }
68
153
 
69
154
  export default vowelStylesPlugin
@@ -0,0 +1,116 @@
1
+ import { hash } from "node:crypto"
2
+ import { typographyCSS } from "../markdown/typography.js"
3
+
4
+ /**
5
+ * The themes vowel ships. A `theme` naming anything else gets no
6
+ * stylesheets at all, which is the behaviour the folder pass had.
7
+ */
8
+ const BUILT_IN_THEMES = ["reset", "typography", "default"]
9
+
10
+ /**
11
+ * A `theme` setting is either a bare name ("default") or an object
12
+ * carrying its own configuration ({name: "Default", colors: [...]}) -
13
+ * which is what `theme.colors` means as a path. Compared
14
+ * case-insensitively: settings.md is written by hand, and "Default" is
15
+ * what a person would type.
16
+ * @param {unknown} themeSetting
17
+ */
18
+ function resolveTheme(themeSetting) {
19
+ const isConfig = themeSetting && typeof themeSetting === "object" && !Array.isArray(themeSetting)
20
+ const config = isConfig ? themeSetting : { name: themeSetting }
21
+ const name = config.name ? String(config.name).toLowerCase() : "default"
22
+ return { config, name, known: BUILT_IN_THEMES.includes(name) }
23
+ }
24
+
25
+ /**
26
+ * A short, stable identity for a theme configuration: its canonical
27
+ * JSON (keys sorted at every depth), hashed. Two settings.md files that
28
+ * spell the same theme get the same key, and the same generated sheets.
29
+ * @param {unknown} themeSetting
30
+ */
31
+ function themeKey(themeSetting) {
32
+ const { config, name } = resolveTheme(themeSetting)
33
+ return hash("MD5", canonical({ ...config, name })).slice(0, 8)
34
+ }
35
+
36
+ /** @param {unknown} value */
37
+ function canonical(value) {
38
+ if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`
39
+ if (value && typeof value === "object") {
40
+ return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonical(value[key])}`).join(",")}}`
41
+ }
42
+ return JSON.stringify(value)
43
+ }
44
+
45
+ /** The generated sheets, the ones a theme's configuration decides. */
46
+ const GENERATED = /^(colors|type)(-[0-9a-f]{8})?\.css$/
47
+
48
+ /** The bundled sheets, part of the software rather than the project. */
49
+ const BUNDLED_SHEETS = ["reset.css", "typography.css", "default.css", "syntax-highlighting.css"]
50
+
51
+ /**
52
+ * The theme's stylesheets, in cascade order.
53
+ *
54
+ * **The single source of truth for two questions that must agree**: which
55
+ * sheets the styles processor declares as stubs, and which sheets a page
56
+ * links. They used to be one list built in the folder pass and written to
57
+ * a `stylesheets` setting that the html plugin read back; the list and the
58
+ * targets were produced by the same block, so they could not disagree.
59
+ * Now that the targets are stubs, this function is what keeps them in
60
+ * step - a sheet that is declared is linked, and nothing links a sheet
61
+ * that was never declared.
62
+ *
63
+ * A theme is a folder setting, so a folder can have its own - and the
64
+ * generated sheets (`colors.css`, `type.css`) are what differ between
65
+ * two themes; the bundled ones are shared. The root's theme keeps the
66
+ * plain names; any other theme's generated sheets carry the theme's
67
+ * key (`colors-3f9a2c1d.css`), so folders sharing a theme share a file
68
+ * and nothing is written twice.
69
+ *
70
+ * `type.css` is emitted only when the theme actually drives dynamic
71
+ * typography, and it comes before `colors.css`/`default.css` because a
72
+ * later `@layer` statement appends unseen layers to the end of the order.
73
+ *
74
+ * Every built-in is named here, `default` included: an undefined theme
75
+ * *is* the default theme, and a folder with none declared inherits
76
+ * whatever its nearest ancestor declared - `reset` at the root means
77
+ * `reset` below it, not `default`.
78
+ * @param {unknown} themeSetting - this folder's resolved theme
79
+ * @param {unknown} [rootThemeSetting] - the root's; omitted means "this
80
+ * is the root's". A rest parameter rather than a default, because an
81
+ * undeclared root theme is a real `undefined` that must not collapse
82
+ * into "same as this one".
83
+ * @returns {string[]}
84
+ */
85
+ function themeStylesheets(themeSetting, ...root) {
86
+ const rootThemeSetting = root.length ? root[0] : themeSetting
87
+ const { config, name, known } = resolveTheme(themeSetting)
88
+ if (!known) return []
89
+
90
+ const key = themeKey(themeSetting)
91
+ const suffix = key === themeKey(rootThemeSetting) ? "" : `-${key}`
92
+ const generated = (sheet) => `${sheet}${suffix}.css`
93
+
94
+ switch (name) {
95
+ case "reset":
96
+ return ["reset.css"]
97
+ case "typography":
98
+ return ["reset.css", "typography.css", ...(typographyCSS(config) ? [generated("type")] : [])]
99
+ case "default":
100
+ return ["reset.css", "typography.css", ...(typographyCSS(config) ? [generated("type")] : []), generated("colors"), "default.css"]
101
+ default:
102
+ return []
103
+ }
104
+ }
105
+
106
+ /**
107
+ * Whether a stylesheet path is vowel's - bundled, or generated from a
108
+ * theme - as opposed to the project's own. Every one of them is a stub
109
+ * with a source path like any other source, so this is the test that
110
+ * separates them.
111
+ */
112
+ function isVowelStylesheet(sheetPath) {
113
+ return BUNDLED_SHEETS.includes(sheetPath) || GENERATED.test(sheetPath)
114
+ }
115
+
116
+ export { resolveTheme, themeStylesheets, themeKey, isVowelStylesheet, BUNDLED_SHEETS, BUILT_IN_THEMES }