obsidian-plugin-dev-kit 0.0.0-stage → 0.3.2

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 (329) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +223 -2
  3. package/bin/opdk.js +34 -0
  4. package/dist/build/args.d.ts +10 -0
  5. package/dist/build/args.js +45 -0
  6. package/dist/build/bundle-check.d.ts +17 -0
  7. package/dist/build/bundle-check.js +42 -0
  8. package/dist/build/bundle-file.d.ts +4 -0
  9. package/dist/build/bundle-file.js +29 -0
  10. package/dist/build/commands.d.ts +5 -0
  11. package/dist/build/commands.js +109 -0
  12. package/dist/build/config.d.ts +3 -0
  13. package/dist/build/config.js +103 -0
  14. package/dist/build/css-imports.d.ts +23 -0
  15. package/dist/build/css-imports.js +50 -0
  16. package/dist/build/css-step.d.ts +10 -0
  17. package/dist/build/css-step.js +27 -0
  18. package/dist/build/css.d.ts +24 -0
  19. package/dist/build/css.js +47 -0
  20. package/dist/build/options.d.ts +55 -0
  21. package/dist/build/options.js +70 -0
  22. package/dist/build/release.d.ts +5 -0
  23. package/dist/build/release.js +34 -0
  24. package/dist/build/report.d.ts +7 -0
  25. package/dist/build/report.js +16 -0
  26. package/dist/build/vault.d.ts +26 -0
  27. package/dist/build/vault.js +290 -0
  28. package/dist/build-info.json +1 -0
  29. package/dist/cli/argv.d.ts +14 -0
  30. package/dist/cli/argv.js +18 -0
  31. package/dist/cli/commands.d.ts +3 -0
  32. package/dist/cli/commands.js +7 -0
  33. package/dist/cli/main.d.ts +2 -0
  34. package/dist/cli/main.js +23 -0
  35. package/dist/cli/process-reporter.d.ts +5 -0
  36. package/dist/cli/process-reporter.js +15 -0
  37. package/dist/cli/registry.d.ts +4 -0
  38. package/dist/cli/registry.js +15 -0
  39. package/dist/cli/reporter.d.ts +53 -0
  40. package/dist/cli/reporter.js +100 -0
  41. package/dist/cli/run.d.ts +9 -0
  42. package/dist/cli/run.js +61 -0
  43. package/dist/cli/types.d.ts +27 -0
  44. package/dist/cli/types.js +1 -0
  45. package/dist/cli/version.d.ts +13 -0
  46. package/dist/cli/version.js +61 -0
  47. package/dist/config/define-config.d.ts +3 -0
  48. package/dist/config/define-config.js +4 -0
  49. package/dist/config/load-config.d.ts +6 -0
  50. package/dist/config/load-config.js +70 -0
  51. package/dist/config/manifest.d.ts +3 -0
  52. package/dist/config/manifest.js +72 -0
  53. package/dist/config/types.d.ts +146 -0
  54. package/dist/config/types.js +23 -0
  55. package/dist/demo/args.d.ts +4 -0
  56. package/dist/demo/args.js +13 -0
  57. package/dist/demo/checks.d.ts +56 -0
  58. package/dist/demo/checks.js +124 -0
  59. package/dist/demo/commands.d.ts +3 -0
  60. package/dist/demo/commands.js +65 -0
  61. package/dist/demo/config.d.ts +57 -0
  62. package/dist/demo/config.js +337 -0
  63. package/dist/demo/ffmpeg-run.d.ts +18 -0
  64. package/dist/demo/ffmpeg-run.js +59 -0
  65. package/dist/demo/ffmpeg.d.ts +63 -0
  66. package/dist/demo/ffmpeg.js +111 -0
  67. package/dist/demo/films.d.ts +46 -0
  68. package/dist/demo/films.js +134 -0
  69. package/dist/demo/phone-layout.d.ts +38 -0
  70. package/dist/demo/phone-layout.js +98 -0
  71. package/dist/demo/phone-render.d.ts +28 -0
  72. package/dist/demo/phone-render.js +124 -0
  73. package/dist/demo/published.d.ts +16 -0
  74. package/dist/demo/published.js +72 -0
  75. package/dist/demo/run.d.ts +31 -0
  76. package/dist/demo/run.js +397 -0
  77. package/dist/demo/stills.d.ts +21 -0
  78. package/dist/demo/stills.js +62 -0
  79. package/dist/e2e/artifacts.d.ts +27 -0
  80. package/dist/e2e/artifacts.js +90 -0
  81. package/dist/e2e/cleanup.d.ts +54 -0
  82. package/dist/e2e/cleanup.js +109 -0
  83. package/dist/e2e/config.d.ts +9 -0
  84. package/dist/e2e/config.js +42 -0
  85. package/dist/e2e/create-test.d.ts +37 -0
  86. package/dist/e2e/create-test.js +109 -0
  87. package/dist/e2e/demo/clip.d.ts +21 -0
  88. package/dist/e2e/demo/clip.js +44 -0
  89. package/dist/e2e/demo/create-demo.d.ts +42 -0
  90. package/dist/e2e/demo/create-demo.js +439 -0
  91. package/dist/e2e/demo/manifest.d.ts +76 -0
  92. package/dist/e2e/demo/manifest.js +168 -0
  93. package/dist/e2e/demo/names.d.ts +18 -0
  94. package/dist/e2e/demo/names.js +44 -0
  95. package/dist/e2e/demo/options.d.ts +22 -0
  96. package/dist/e2e/demo/options.js +59 -0
  97. package/dist/e2e/demo/ownership.d.ts +27 -0
  98. package/dist/e2e/demo/ownership.js +65 -0
  99. package/dist/e2e/demo/page-scripts.d.ts +82 -0
  100. package/dist/e2e/demo/page-scripts.js +250 -0
  101. package/dist/e2e/demo/png.d.ts +8 -0
  102. package/dist/e2e/demo/png.js +23 -0
  103. package/dist/e2e/demo/presets.d.ts +43 -0
  104. package/dist/e2e/demo/presets.js +20 -0
  105. package/dist/e2e/demo/privacy.d.ts +18 -0
  106. package/dist/e2e/demo/privacy.js +30 -0
  107. package/dist/e2e/demo/still-options.d.ts +22 -0
  108. package/dist/e2e/demo/still-options.js +68 -0
  109. package/dist/e2e/demo/types.d.ts +184 -0
  110. package/dist/e2e/demo/types.js +1 -0
  111. package/dist/e2e/electron-binary.d.ts +15 -0
  112. package/dist/e2e/electron-binary.js +30 -0
  113. package/dist/e2e/fixtures.d.ts +62 -0
  114. package/dist/e2e/fixtures.js +68 -0
  115. package/dist/e2e/gate.d.ts +4 -0
  116. package/dist/e2e/gate.js +8 -0
  117. package/dist/e2e/global-setup.d.ts +11 -0
  118. package/dist/e2e/global-setup.js +17 -0
  119. package/dist/e2e/helpers/commands.d.ts +14 -0
  120. package/dist/e2e/helpers/commands.js +56 -0
  121. package/dist/e2e/helpers/create-helpers.d.ts +24 -0
  122. package/dist/e2e/helpers/create-helpers.js +582 -0
  123. package/dist/e2e/helpers/device-metrics.d.ts +21 -0
  124. package/dist/e2e/helpers/device-metrics.js +25 -0
  125. package/dist/e2e/helpers/ime.d.ts +13 -0
  126. package/dist/e2e/helpers/ime.js +19 -0
  127. package/dist/e2e/helpers/layout-page-scripts.d.ts +103 -0
  128. package/dist/e2e/helpers/layout-page-scripts.js +224 -0
  129. package/dist/e2e/helpers/layout.d.ts +83 -0
  130. package/dist/e2e/helpers/layout.js +148 -0
  131. package/dist/e2e/helpers/mobile.d.ts +31 -0
  132. package/dist/e2e/helpers/mobile.js +26 -0
  133. package/dist/e2e/helpers/page-scripts.d.ts +194 -0
  134. package/dist/e2e/helpers/page-scripts.js +467 -0
  135. package/dist/e2e/helpers/settings.d.ts +8 -0
  136. package/dist/e2e/helpers/settings.js +16 -0
  137. package/dist/e2e/helpers/settle.d.ts +28 -0
  138. package/dist/e2e/helpers/settle.js +33 -0
  139. package/dist/e2e/helpers/types.d.ts +193 -0
  140. package/dist/e2e/helpers/types.js +1 -0
  141. package/dist/e2e/helpers/view-mode.d.ts +23 -0
  142. package/dist/e2e/helpers/view-mode.js +35 -0
  143. package/dist/e2e/index.d.ts +14 -0
  144. package/dist/e2e/index.js +4 -0
  145. package/dist/e2e/internals.d.ts +155 -0
  146. package/dist/e2e/internals.js +8 -0
  147. package/dist/e2e/obsidian-path.d.ts +17 -0
  148. package/dist/e2e/obsidian-path.js +31 -0
  149. package/dist/e2e/options.d.ts +123 -0
  150. package/dist/e2e/options.js +244 -0
  151. package/dist/e2e/page-scripts.d.ts +45 -0
  152. package/dist/e2e/page-scripts.js +53 -0
  153. package/dist/e2e/peers.d.ts +9 -0
  154. package/dist/e2e/peers.js +19 -0
  155. package/dist/e2e/plugins.d.ts +32 -0
  156. package/dist/e2e/plugins.js +119 -0
  157. package/dist/e2e/process-tree.d.ts +33 -0
  158. package/dist/e2e/process-tree.js +133 -0
  159. package/dist/e2e/readiness.d.ts +23 -0
  160. package/dist/e2e/readiness.js +63 -0
  161. package/dist/e2e/seed.d.ts +34 -0
  162. package/dist/e2e/seed.js +122 -0
  163. package/dist/e2e/session.d.ts +71 -0
  164. package/dist/e2e/session.js +266 -0
  165. package/dist/e2e/vault.d.ts +52 -0
  166. package/dist/e2e/vault.js +146 -0
  167. package/dist/e2e/version.d.ts +25 -0
  168. package/dist/e2e/version.js +40 -0
  169. package/dist/eslint/index.d.ts +2 -0
  170. package/dist/eslint/index.js +1 -0
  171. package/dist/eslint/obsidian-plugin.d.ts +49 -0
  172. package/dist/eslint/obsidian-plugin.js +115 -0
  173. package/dist/index.d.ts +3 -0
  174. package/dist/index.js +1 -0
  175. package/dist/kit/args.d.ts +7 -0
  176. package/dist/kit/args.js +21 -0
  177. package/dist/kit/commands.d.ts +3 -0
  178. package/dist/kit/commands.js +52 -0
  179. package/dist/kit/files.d.ts +3 -0
  180. package/dist/kit/files.js +24 -0
  181. package/dist/kit/pins.d.ts +89 -0
  182. package/dist/kit/pins.js +178 -0
  183. package/dist/kit/remote.d.ts +13 -0
  184. package/dist/kit/remote.js +33 -0
  185. package/dist/kit/runners.d.ts +11 -0
  186. package/dist/kit/runners.js +53 -0
  187. package/dist/kit/terminal-text.d.ts +6 -0
  188. package/dist/kit/terminal-text.js +20 -0
  189. package/dist/kit/upgrade.d.ts +26 -0
  190. package/dist/kit/upgrade.js +162 -0
  191. package/dist/peers/resolve.d.ts +8 -0
  192. package/dist/peers/resolve.js +28 -0
  193. package/dist/peers/versions.d.ts +30 -0
  194. package/dist/peers/versions.js +32 -0
  195. package/dist/release/api-check.d.ts +27 -0
  196. package/dist/release/api-check.js +119 -0
  197. package/dist/release/args.d.ts +40 -0
  198. package/dist/release/args.js +120 -0
  199. package/dist/release/assets.d.ts +21 -0
  200. package/dist/release/assets.js +35 -0
  201. package/dist/release/build-check.d.ts +43 -0
  202. package/dist/release/build-check.js +184 -0
  203. package/dist/release/build-script.d.ts +12 -0
  204. package/dist/release/build-script.js +30 -0
  205. package/dist/release/build-tagged.d.ts +26 -0
  206. package/dist/release/build-tagged.js +52 -0
  207. package/dist/release/bump.d.ts +24 -0
  208. package/dist/release/bump.js +58 -0
  209. package/dist/release/changelog.d.ts +25 -0
  210. package/dist/release/changelog.js +148 -0
  211. package/dist/release/check.d.ts +38 -0
  212. package/dist/release/check.js +150 -0
  213. package/dist/release/commands.d.ts +3 -0
  214. package/dist/release/commands.js +154 -0
  215. package/dist/release/committed-tree.d.ts +63 -0
  216. package/dist/release/committed-tree.js +118 -0
  217. package/dist/release/config.d.ts +3 -0
  218. package/dist/release/config.js +28 -0
  219. package/dist/release/gh-access.d.ts +14 -0
  220. package/dist/release/gh-access.js +45 -0
  221. package/dist/release/gh.d.ts +10 -0
  222. package/dist/release/gh.js +33 -0
  223. package/dist/release/git.d.ts +49 -0
  224. package/dist/release/git.js +111 -0
  225. package/dist/release/interrupt.d.ts +30 -0
  226. package/dist/release/interrupt.js +60 -0
  227. package/dist/release/json.d.ts +33 -0
  228. package/dist/release/json.js +81 -0
  229. package/dist/release/kit-check.d.ts +8 -0
  230. package/dist/release/kit-check.js +51 -0
  231. package/dist/release/manifest-rules.d.ts +23 -0
  232. package/dist/release/manifest-rules.js +255 -0
  233. package/dist/release/preflight.d.ts +10 -0
  234. package/dist/release/preflight.js +65 -0
  235. package/dist/release/problems.d.ts +24 -0
  236. package/dist/release/problems.js +11 -0
  237. package/dist/release/project-files.d.ts +14 -0
  238. package/dist/release/project-files.js +16 -0
  239. package/dist/release/publish-command.d.ts +21 -0
  240. package/dist/release/publish-command.js +83 -0
  241. package/dist/release/publish-git.d.ts +37 -0
  242. package/dist/release/publish-git.js +108 -0
  243. package/dist/release/publish-state.d.ts +29 -0
  244. package/dist/release/publish-state.js +70 -0
  245. package/dist/release/publish-verify.d.ts +41 -0
  246. package/dist/release/publish-verify.js +112 -0
  247. package/dist/release/publish-wait.d.ts +25 -0
  248. package/dist/release/publish-wait.js +56 -0
  249. package/dist/release/publish.d.ts +35 -0
  250. package/dist/release/publish.js +181 -0
  251. package/dist/release/release-assets.d.ts +39 -0
  252. package/dist/release/release-assets.js +68 -0
  253. package/dist/release/release.d.ts +37 -0
  254. package/dist/release/release.js +179 -0
  255. package/dist/release/remote.d.ts +12 -0
  256. package/dist/release/remote.js +15 -0
  257. package/dist/release/reproducible.d.ts +16 -0
  258. package/dist/release/reproducible.js +34 -0
  259. package/dist/release/run-tests.d.ts +5 -0
  260. package/dist/release/run-tests.js +17 -0
  261. package/dist/release/semver.d.ts +8 -0
  262. package/dist/release/semver.js +60 -0
  263. package/dist/release/version-rules.d.ts +28 -0
  264. package/dist/release/version-rules.js +63 -0
  265. package/dist/release/versions-json.d.ts +15 -0
  266. package/dist/release/versions-json.js +88 -0
  267. package/dist/release/workflow-run.d.ts +44 -0
  268. package/dist/release/workflow-run.js +71 -0
  269. package/dist/scanner/code-checks.d.ts +41 -0
  270. package/dist/scanner/code-checks.js +82 -0
  271. package/dist/scanner/commands.d.ts +3 -0
  272. package/dist/scanner/commands.js +43 -0
  273. package/dist/scanner/config.d.ts +7 -0
  274. package/dist/scanner/config.js +25 -0
  275. package/dist/scanner/css-check.d.ts +26 -0
  276. package/dist/scanner/css-check.js +63 -0
  277. package/dist/scanner/eslint-nesting.d.ts +16 -0
  278. package/dist/scanner/eslint-nesting.js +45 -0
  279. package/dist/scanner/findings.d.ts +23 -0
  280. package/dist/scanner/findings.js +21 -0
  281. package/dist/scanner/git-files.d.ts +16 -0
  282. package/dist/scanner/git-files.js +73 -0
  283. package/dist/scanner/lint.d.ts +47 -0
  284. package/dist/scanner/lint.js +163 -0
  285. package/dist/scanner/meta-checks.d.ts +8 -0
  286. package/dist/scanner/meta-checks.js +22 -0
  287. package/dist/scanner/outside-project.d.ts +19 -0
  288. package/dist/scanner/outside-project.js +20 -0
  289. package/dist/scanner/run.d.ts +19 -0
  290. package/dist/scanner/run.js +78 -0
  291. package/dist/scanner/scanner-config.d.ts +114 -0
  292. package/dist/scanner/scanner-config.js +207 -0
  293. package/dist/scanner/typescript-gate.d.ts +30 -0
  294. package/dist/scanner/typescript-gate.js +73 -0
  295. package/dist/vitest/build-config.d.ts +17 -0
  296. package/dist/vitest/build-config.js +106 -0
  297. package/dist/vitest/define-unit-config.d.ts +27 -0
  298. package/dist/vitest/define-unit-config.js +45 -0
  299. package/dist/vitest/dom/elements.d.ts +87 -0
  300. package/dist/vitest/dom/elements.js +291 -0
  301. package/dist/vitest/dom/index.d.ts +1 -0
  302. package/dist/vitest/dom/index.js +1 -0
  303. package/dist/vitest/dom/install.d.ts +8 -0
  304. package/dist/vitest/dom/install.js +261 -0
  305. package/dist/vitest/dom/setup.d.ts +1 -0
  306. package/dist/vitest/dom/setup.js +3 -0
  307. package/dist/vitest/index.d.ts +3 -0
  308. package/dist/vitest/index.js +2 -0
  309. package/dist/vitest/options.d.ts +92 -0
  310. package/dist/vitest/options.js +136 -0
  311. package/dist/vitest/peers.d.ts +10 -0
  312. package/dist/vitest/peers.js +51 -0
  313. package/dist/vitest/workspace-root.d.ts +7 -0
  314. package/dist/vitest/workspace-root.js +39 -0
  315. package/docs/build.md +232 -0
  316. package/docs/ci.md +182 -0
  317. package/docs/demo.md +364 -0
  318. package/docs/e2e.md +563 -0
  319. package/docs/release.md +374 -0
  320. package/docs/scanner.md +204 -0
  321. package/docs/unit.md +291 -0
  322. package/package.json +100 -4
  323. package/plugins/opdk/skills/audit/SKILL.md +81 -0
  324. package/plugins/opdk/skills/build/SKILL.md +79 -0
  325. package/plugins/opdk/skills/demo/SKILL.md +102 -0
  326. package/plugins/opdk/skills/e2e/SKILL.md +132 -0
  327. package/plugins/opdk/skills/release/SKILL.md +84 -0
  328. package/plugins/opdk/skills/scanner/SKILL.md +60 -0
  329. package/plugins/opdk/skills/unit/SKILL.md +90 -0
@@ -0,0 +1,374 @@
1
+ # Releases
2
+
3
+ `opdk release check` tells you whether a commit can be released. `opdk release patch` (or `minor`, `major`, or an exact `X.Y.Z`) bumps the version in every file, tags the commit, pushes the tag, waits for the kit's reusable GitHub workflow, verifies the draft release it made, publishes it and only then pushes the branch. `opdk release publish` continues that flow after any stop, and `opdk release notes` prints a version's CHANGELOG section.
4
+
5
+ ## Why
6
+
7
+ Obsidian reads the version from `manifest.json` on the default branch, then downloads `main.js`, `manifest.json` and `styles.css` from the GitHub release with that tag. Since 2026-05 the community directory scans every release. Its [documentation](https://docs.obsidian.md/community-directory/manage-entry) says it verifies that the build matches what is committed, and developers report that `main.js` is compared byte for byte. Hand-written release scripts in real plugins had these problems:
8
+
9
+ - **Branch and tag were pushed together** (`git push --follow-tags`), so the directory could read the new `manifest.json` before the release workflow had finished, or after it failed.
10
+ - **GitHub's release listing can lag behind a successful release.** A plugin's 1.0.2 release failed its directory review with "release is missing the main.js file" although the release had its assets: the list of assets of the release stayed empty for 90 minutes after a successful run. The kit cannot shorten that wait. It makes sure the manifest on the default branch moves only after the release is public.
11
+ - **The audit exited 0 on problems.** A `release-audit.cjs` script printed its findings and "READY FOR OBSIDIAN REVIEW ❌", then exited 0 (it exited 1 only when no zip was found), and its zip step dropped a missing `main.js` without a word.
12
+ - **`versions.json` entries could be rewritten.** A `version-sync.cjs` script rewrote an existing entry whenever `minAppVersion` changed, including the entry of a released version. Another plugin had no `versions.json` at all and never compared the tag with the manifest.
13
+ - **The CHANGELOG never reached the release.** Plugins keep a hand-written CHANGELOG, and the release page showed GitHub's list of pull requests (or only a compare link).
14
+ - **Any tag built from any commit.** A tag on a commit outside the default branch was built and published as it was.
15
+ - **Attestations were produced and never verified.**
16
+
17
+ The kit's answer, in the same order: the tag is pushed first and the branch last; the check exits 1 with a hint per problem; a `versions.json` entry is added and never rewritten; the release notes are the CHANGELOG section; the workflow refuses a tag that is not the manifest version on top of the default branch; and the draft's bytes and attestations are verified before it is made public.
18
+
19
+ ## Quick start
20
+
21
+ 1. Install the kit as a dev dependency (see the README) and make `scripts.build` run `opdk build`:
22
+
23
+ ```json
24
+ {
25
+ "scripts": {
26
+ "build": "opdk build"
27
+ }
28
+ }
29
+ ```
30
+
31
+ The community directory rebuilds `main.js` with the first of `build`, `build:plugin` and `compile` that exists. `opdk release` compares the release assets byte for byte with its own `opdk build` of the tag, so that script has to run `opdk build`.
32
+
33
+ 2. Add a workflow that calls the kit's. The permissions block is required: a called workflow cannot ask for more than its caller grants. Pin the kit to a full commit SHA, not to a branch or a tag name:
34
+
35
+ ```yaml
36
+ # .github/workflows/release.yml
37
+ name: Release
38
+ on:
39
+ push:
40
+ tags: ['*.*.*']
41
+ permissions:
42
+ contents: write
43
+ id-token: write
44
+ attestations: write
45
+ jobs:
46
+ release:
47
+ uses: Dimagious/obsidian-plugin-dev-kit/.github/workflows/release.yml@<full commit SHA of the kit>
48
+ ```
49
+
50
+ 3. Keep a `CHANGELOG.md` with an `## [Unreleased]` section, and a `versions.json` that maps your current version to `minAppVersion` (see "Requirements").
51
+
52
+ 4. Look at what would stop a release, in CI or by hand:
53
+
54
+ ```bash
55
+ npx opdk release check
56
+ ```
57
+
58
+ 5. Cut the release from the default branch with a clean tree:
59
+
60
+ ```bash
61
+ npx opdk release patch --dry-run # everything but the commit, the tag and the pushes; prints the diff
62
+ npx opdk release patch
63
+ ```
64
+
65
+ ## Requirements
66
+
67
+ - **The GitHub CLI (`gh`)**, signed in with write access to the repository `origin` points at. `opdk release` checks this before it bumps anything, so a missing `gh` leaves the tree as it was. `--no-push` and `--dry-run` skip the check.
68
+ - **`origin` is a GitHub URL**: `https://host/<owner>/<repo>[.git]`, `ssh://git@host/<owner>/<repo>[.git]` (also `git://` and `git+ssh://`), or `git@host:<owner>/<repo>[.git]`. The host is ignored, `gh` asks github.com. A local path or a URL with more path segments is refused.
69
+ - **`scripts.build` runs `opdk build`** (see Quick start).
70
+ - **`versions.json`** exists, is an object, and maps the current version to the manifest's `minAppVersion`. `opdk release <bump>` creates a missing file, but `opdk release check` fails without it, so add it first when you want the check in CI.
71
+ - **`CHANGELOG.md`** in Keep a Changelog form: `## [Unreleased]` with entries before a release, `## [X.Y.Z]` after it. The file is `CHANGELOG.md` unless `release.changelog` names another.
72
+ - **A tag workflow in the plugin that calls the kit's `release.yml`** (see Quick start). The plugin installs `opdk` as a dev dependency, because the workflow runs `node_modules/.bin/opdk`.
73
+ - **Actions enabled** for the repository, with workflow permissions that allow the caller's `permissions` block (Settings, Actions, General).
74
+ - A **default branch** git can find: `origin/HEAD`, or `release.defaultBranch`. If `origin/HEAD` is not set, run `git remote set-head origin --auto`.
75
+
76
+ ## `opdk release check`
77
+
78
+ For CI and for the minute before a release. Exit 1 with one `✗` line and a hint per problem; warnings print as `!` and do not fail.
79
+
80
+ | Group | What it checks |
81
+ |---|---|
82
+ | `versions` | `manifest.json`, `package.json` and `package-lock.json` (both version fields) hold the same `x.y.z` version, with no `v` and no pre-release. With `--tag <name>`, or `GITHUB_REF_NAME` when `GITHUB_REF_TYPE=tag`, the tag is that version. A missing lockfile is a warning. `package.json`, `package-lock.json` and `manifest.json` must also be written the way `JSON.stringify` writes them (their own indent, final newline, consistent line endings): `opdk release <bump>` rewrites them and refuses a file it cannot write back as it is |
83
+ | `versions.json` | The file exists and is an object; the current version maps to the manifest's `minAppVersion`; `minAppVersion` never goes down as versions go up (errors), and the file is formatted the way `JSON.stringify` writes it, so a one-line `{"1.7.1": "1.5.0"}` fails with a `node -e` command that rewrites it (Prettier would leave it on one line). A key or value that is not a version is a warning, as in the official action |
84
+ | `manifest` | The rules of the official [`obsidianmd/obsidian-workflows`](https://github.com/obsidianmd/obsidian-workflows) action (v1.2.3): required fields, `id`, `name` and `description` rules, an `author` without an email or a URL, HTTPS URLs, `isDesktopOnly` a boolean, version not `0.0.0`, `minAppVersion` a version |
85
+ | `changelog` | `CHANGELOG.md` has a `## [X.Y.Z]` section with at least one entry |
86
+ | `kit` | When the plugin depends on the kit, its three pins name one release: the tag in `package.json`, the commit the lockfile resolved it to, and the commit in every `uses: <owner>/obsidian-plugin-dev-kit/.github/workflows/<file>@<sha> # vX.Y.Z` line of `.github/workflows/*.yml`. It works offline: the lockfile's `version` stands for the tag, and a `# vX.Y.Z` comment must match it. A workflow pinned to a tag or a branch instead of a full commit SHA fails. A plugin that does not use the kit, or does not call its workflows, passes. The failure lists every place with the commit it names and the fix, `opdk kit upgrade` (see [Updating the kit](ci.md#updating-the-kit)) |
87
+ | `build` | A production build into temp folders (your `main.js` and `styles.css` are not touched) passes the Node-only bundle check. Warns when `scripts.build` (else `build:plugin`, else `compile`) does not run `opdk build` |
88
+ | `assets` | `main.js` is produced, `styles.css` when the plugin has CSS, and the manifest asset is the root `manifest.json` |
89
+ | `reproducible` | The working tree is built, then the committed tree, and `main.js` and `styles.css` must match byte for byte |
90
+ | `api` | `minAppVersion` against the API the code calls (`obsidianmd/no-unsupported-api`) |
91
+
92
+ `opdk scan` is not part of the check. Run it separately.
93
+
94
+ ### Where the manifest rules differ from the official action
95
+
96
+ The kit follows the action's `src/manifest.ts` with these differences:
97
+
98
+ - `author`, `minAppVersion` and `isDesktopOnly` are required. The action only recommends them.
99
+ - A banned word in the `id` is a warning, in the `name` an error.
100
+ - `helpUrl` is accepted and its URL is checked.
101
+ - `authorUrl`, `helpUrl` and `fundingUrl` of the wrong type (an array, a number) are errors.
102
+ - The action's check that `authorUrl` is not the plugin's own repository is covered by the general warning that `authorUrl` links to a repository.
103
+
104
+ ### Reproducibility, and what it does not prove
105
+
106
+ The directory rebuilds your plugin from the tagged commit. A build that depends on something git does not hold passes on your machine and fails there. The check builds the working tree, then extracts `git archive HEAD` into another temp folder (with your `node_modules` linked in) and builds that. A mismatch names the first differing offset and the likely causes. It catches an untracked or ignored file that a build input needs (the committed tree does not build) and absolute paths of this machine in the output.
107
+
108
+ Its limits:
109
+
110
+ - It reuses this machine's `node_modules`, so it does not compare the Node or esbuild version, lockfile drift, or line endings on another operating system.
111
+ - With uncommitted changes, the committed tree is what is compared and the output says so.
112
+ - Outside a git repository, or before the first commit, it builds the working tree twice and warns that this proves much less.
113
+ - pnpm and Yarn PnP installs fall back to two builds of the working tree, with a warning that names the layout, because their packages cannot be linked into a copy.
114
+ - `git archive` applies `export-ignore` from `.gitattributes`, and Git LFS files are pointer text in it. A build input that is ignored on export, or tracked by LFS, makes the comparison differ.
115
+
116
+ When `opdk release` publishes, the assets are compared again, this time with GitHub's build of the tag (see step 8 below).
117
+
118
+ ### The build script warning
119
+
120
+ The directory rebuilds `main.js` with `scripts.build` (else `build:plugin`, else `compile`). If that script does not run `opdk build`, the check prints a warning, because the bytes the directory builds may differ from the bytes the kit builds and verifies.
121
+
122
+ ### The API check and its blind spot
123
+
124
+ `obsidianmd/no-unsupported-api` runs type-aware against the manifest's `minAppVersion`, over the files esbuild puts into `main.js` (read from its metafile, `node_modules` excluded). It needs `npm ci` first. A shipped file that no tsconfig covers is an error.
125
+
126
+ The rule reads `@since` tags from `obsidian.d.ts` through the TypeScript program. When the program does not contain the real `obsidian.d.ts` (for example a tsconfig `paths` entry that points `obsidian` at a stub), the rule reports nothing and the check cannot tell.
127
+
128
+ ### Skipping parts
129
+
130
+ | Flag | Skips |
131
+ |---|---|
132
+ | `--no-build` | `build`, `assets` and `reproducible` (a quick CI step) |
133
+ | `--no-reproducible` | the second build: it builds once |
134
+ | `--no-api` | the API check |
135
+
136
+ The version, `versions.json`, manifest, kit and changelog checks always run.
137
+
138
+ ## `opdk release <bump>`
139
+
140
+ `<bump>` is `patch`, `minor`, `major` or an exact `X.Y.Z`. A `v` prefix and pre-release versions are refused with a message that says what to type.
141
+
142
+ 1. **Preflight.** The folder is a git repository with a clean tree, on the default branch, neither behind nor ahead of `origin` (it runs `git fetch --no-tags origin`, never a push), the tag does not exist locally or on `origin`, the three versions agree before the bump, the new version is higher than the current one, and `## [Unreleased]` has entries. Every problem prints with a hint. Then `gh` access is checked (skipped with `--no-push` and `--dry-run`). Commits that `origin` has not seen are refused, not warned about: the tag is pushed before the branch, so they would reach the release workflow without having run in the branch's CI. Push them through a pull request, wait for CI, pull, and rerun.
143
+ 2. **Tests.** `npm test` runs on the tree as it is, with its output on the terminal, before any file changes. A failure stops the release with nothing modified. CI already ran the tests for the pushed commits; this run protects the release commit on your machine. `--no-test` skips it, and a `package.json` without a `test` script prints a warning and goes on. A dry run runs the tests too.
144
+ 3. **Bump.** The version is set in `package.json`, `package-lock.json` and `manifest.json`. It is added to `versions.json` mapped to `minAppVersion`: an existing entry is never rewritten, and a missing file is created. The `[Unreleased]` entries move under `## [X.Y.Z] - YYYY-MM-DD`, leaving an empty `[Unreleased]`, and the compare links at the bottom are updated when the file has them.
145
+ 4. **Check.** `opdk release check` runs on the result, with the bumped files laid over the committed tree so that tree matches the commit to come. When it fails, or on Ctrl+C (exit 130), the files are restored, the temp folders are removed and nothing is committed.
146
+ 5. **Commit and tag.** `chore(release): X.Y.Z`, then the annotated tag object `X.Y.Z`. With `--no-push` the command stops here. With `--dry-run` it stops before the commit, prints the diff and restores the files: no commit or tag is created, nothing is pushed and `gh` is never called, but preflight still fetches from `origin` and asks it for the tag (`ls-remote`).
147
+ 6. **Push the tag.** Only `git push origin refs/tags/X.Y.Z`. The branch waits. There is no force flag in the code, and a tag on `origin` that is not this tag object (it points elsewhere) stops the flow.
148
+ 7. **Wait for the workflow.** The run is found by the tagged commit and the tag (`head_branch`), among the runs whose `referenced_workflows` include the kit's `release.yml`. Other workflows on the same push, such as a Pages deploy, are not waited for. If no such run starts within 3 minutes, the plugin's tag workflow does not call the kit's. A progress line prints whenever the state changes, and every minute while it does not. The default wait is 20 minutes (`--timeout <minutes>`).
149
+ 8. **Verify the draft.**
150
+ - It holds `main.js`, `manifest.json` and `styles.css` only when the plugin has CSS, each uploaded and not empty, and nothing else (`--zip` also expects `<id>-<version>.zip`). Two releases for one tag stop the flow. A release that is already public (a resume) is verified the same way.
151
+ - Its notes equal the `## [X.Y.Z]` section of the CHANGELOG as committed at the tag (trailing whitespace aside).
152
+ - The assets are downloaded and compared byte for byte with a build of the tagged commit made on your machine (`git archive` of the tag, built like the reproducibility check does) and with the committed `manifest.json`. The zip is checked for presence and size only.
153
+ - `gh attestation verify` runs for each attested file against the repository, the tag ref, the tagged commit and the signer. The signer identity must match `^https://github\.com/Dimagious/obsidian-plugin-dev-kit/\.github/workflows/release\.yml@`: the kit's `release.yml` at any ref.
154
+ 9. **Publish.** `gh release edit X.Y.Z --draft=false --latest`, then it confirms the release is public and GitHub's latest release.
155
+ 10. **Push the branch.** `git push origin <release commit>:refs/heads/<default branch>`, no force. Later local commits stay local, and nothing is pushed when `origin` already holds the commit. From this moment Obsidian reads the new version.
156
+ 11. **Summary.** The release URL, the workflow run URL and the branch.
157
+
158
+ ### Every stop, and what to do
159
+
160
+ Every stop from the `gh` check on prints where it stopped; the stops of the push flow also print what is on `origin` and the command to resume, and the local ones (tests, check) say what to fix and rerun. Ctrl+C does the same and exits 130. The steps check what is already done, so resuming is safe from any of them.
161
+
162
+ | Stopped at | State | What to do |
163
+ |---|---|---|
164
+ | Preflight, `gh` check | Nothing was pushed or changed | Fix the printed problem and rerun |
165
+ | The tests (`npm test`, before the bump) | Nothing was changed | Fix the tests and rerun `opdk release <bump>`. `--no-test` only when they are covered elsewhere |
166
+ | The check, after the bump | Files restored, nothing committed | Fix and rerun `opdk release <bump>` |
167
+ | Pushing the tag | The tag was not pushed (after Ctrl+C it may have arrived: check with `git ls-remote --tags origin X.Y.Z`) | `opdk release publish X.Y.Z` |
168
+ | No workflow run within 3 minutes | The tag is on `origin` | Make the plugin's tag workflow call the kit's `release.yml`, enable Actions, then `opdk release publish X.Y.Z`. The tag is not pushed twice |
169
+ | The workflow failed, was cancelled, or ran past `--timeout` | The tag is on `origin`, the release is at most a draft | Read the run log (the URL is printed). Either release a new patch version, or re-run the failed jobs on GitHub and then `opdk release publish X.Y.Z`. A failed run can leave a draft behind: delete that draft before re-running, because a re-run creates the release again and may fail on the existing one. After a timeout, wait for the run and use `--timeout` |
170
+ | The workflow succeeded and there is no release | Tag on `origin` | Read the run log, fix the cause and release a new patch version |
171
+ | The draft does not match (assets, notes, bytes, attestations) | Nothing was published | Do not edit the assets. Delete the draft, fix the cause (a Node or dependency version in CI and a build that is not reproducible are the usual ones) and release a new patch version with `opdk release patch`. The tag stays |
172
+ | Two releases for one tag | Nothing was published | Delete the extra draft on GitHub, then `opdk release publish X.Y.Z` |
173
+ | The tag on `origin` points elsewhere, or the tag's `manifest.json` has another version | Nothing was published | A new patch version. Tags are never moved or deleted |
174
+ | The tag is lightweight | Nothing was pushed | A new patch version. Release tags are annotated |
175
+ | Publishing, or marking the release latest | The release is public or a draft | Follow the printed link and fix by hand, then `opdk release publish X.Y.Z` pushes the branch |
176
+ | Pushing the branch (origin has newer commits) | The release is already public | Merge `origin`'s commits without rewriting the release commit: `git pull --no-rebase origin <branch>`, then `git push origin <branch>` |
177
+ | Pushing the branch (refused by the server) | The release is already public | Pulling will not help. Get the release commit onto the branch the way the rule allows (a pull request, or an account that may bypass the rule). A merge that keeps the tagged commit lets `opdk release publish X.Y.Z` finish without pushing; after a squash merge the tagged commit is not on the branch and `publish` would try to push it again. This stop is chosen when git's error gives the reason "protected branch hook declined", "push declined due to repository rule violations" or "pre-receive hook declined", or GitHub's code `GH006` or `GH013`; anything else rejected gets the pull hint above |
178
+
179
+ A stop whose own hint says to release a new version prints `opdk release patch` instead of the resume line, because resuming would stop at the same place. A release that is already public never gets "delete the draft": the message says it is public and not to delete it.
180
+
181
+ ## `opdk release publish [X.Y.Z]`
182
+
183
+ Starts the push flow (steps 6 to 10) from an existing local tag. Use it to resume, or after `--no-push`. Without a version it uses the version in `manifest.json`. It needs the local annotated tag, the tag's commit on the local default branch, and `gh` signed in with write access. It takes `--timeout <minutes>` and `--zip`.
184
+
185
+ ## `opdk release notes [X.Y.Z]`
186
+
187
+ Prints the body of the `## [X.Y.Z]` section of the CHANGELOG, by default for the version in `manifest.json`. The release workflow uses it for the release notes. Exit 1, with a message, when the section is missing or empty.
188
+
189
+ ## The reusable workflow
190
+
191
+ `.github/workflows/release.yml` in this repository is a `workflow_call` workflow. A plugin calls it from a tiny workflow of its own (Quick start) and passes inputs with `with:`:
192
+
193
+ | Input | Type | Default | What it does |
194
+ |---|---|---|---|
195
+ | `node-version` | string | `"22"` | Node.js version for `npm ci` and the build |
196
+ | `zip` | boolean | `false` | Also attach `<plugin id>-<version>.zip` (`main.js`, `manifest.json`, `styles.css`). Obsidian does not read it. Use `opdk release --zip` together with it |
197
+ | `runs-on` | string | `ubuntu-24.04` | Runner label for both jobs. Pinned, not `ubuntu-latest`; see [ci.md](ci.md#why-ubuntu-2404) |
198
+
199
+ Two jobs:
200
+
201
+ - **`build`**, with `contents: read` only. It checks out the full history, runs everything that executes plugin code (`npm ci` with no npm cache, `opdk release check --tag`, the build script) and hands `main.js`, `manifest.json`, `styles.css` when present, and the release notes over as a workflow artifact.
202
+ - **`release`**, with `contents: write`, `id-token: write` and `attestations: write`. It runs no checkout, no npm and no plugin code. It checks that the artifact holds only the expected files, attests `main.js`, `manifest.json` and `styles.css` with `actions/attest-build-provenance`, and creates a **draft** release named after the tag with the CHANGELOG section as notes. It never publishes.
203
+
204
+ What it refuses:
205
+
206
+ - A run that is not for a pushed tag.
207
+ - A tag that is not the `manifest.json` version.
208
+ - A tag whose commit is not on top of `origin/<default branch>`. The branch is pushed after the release, so the release commit is ahead of it by design; the tip of the default branch must be an ancestor of the tagged commit. A push to the branch after the release commit was made breaks that, and the message says to release again from an up-to-date branch.
209
+ - A failing `opdk release check`.
210
+ - A plugin whose `package.json` has none of the scripts `build`, `build:plugin`, `compile`, or whose build leaves no `main.js` or `manifest.json`.
211
+ - A `<plugin id>` that is not safe in a file name, when `zip` is on.
212
+ - A tag that already has a release: this is GitHub's and `gh`'s behaviour when the draft is created, not a check in the workflow.
213
+
214
+ Every third-party action is pinned to a full commit SHA, with its version in a comment.
215
+
216
+ **The workflow runs the plugin's build and release check, not its tests.** `opdk release` runs `npm test` on your machine before it creates the release commit, and CI has run the tests of every pushed commit, but the tag workflow itself does not. A plugin that wants the tag to wait for a green test run adds its own job and makes the kit's job depend on it:
217
+
218
+ ```yaml
219
+ jobs:
220
+ test:
221
+ runs-on: ubuntu-24.04
222
+ steps:
223
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
224
+ with:
225
+ persist-credentials: false
226
+ - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
227
+ with:
228
+ node-version: 22
229
+ - run: npm ci
230
+ - run: npm test
231
+ release:
232
+ needs: test
233
+ uses: Dimagious/obsidian-plugin-dev-kit/.github/workflows/release.yml@<full commit SHA of the kit>
234
+ ```
235
+
236
+ The `permissions:` block of the caller stays as in the Quick start. `opdk release` finds the kit's run by the workflows it references, so the extra job does not confuse it; the 3-minute wait for a run to start then includes the time the tests take.
237
+
238
+ **Call it, do not copy it.** The attestations are signed by this workflow, and `opdk release` verifies that the signer identity is the kit's `release.yml`. A copy in the plugin's repository is signed as the plugin's file, so the release stops before it is published. The same goes for pinning: use a full commit SHA of the kit so a moved tag cannot change what runs with your `contents: write` token.
239
+
240
+ ## Configuration
241
+
242
+ `opdk.config.mjs`, section `release`, all optional:
243
+
244
+ | Key | Type | Default | What it does |
245
+ |---|---|---|---|
246
+ | `changelog` | string | `CHANGELOG.md` | The changelog file, a path inside the plugin folder (no absolute path, no `..`) |
247
+ | `defaultBranch` | string | from `origin/HEAD` | The branch releases are cut from and pushed to |
248
+
249
+ ```js
250
+ import { defineConfig } from "obsidian-plugin-dev-kit";
251
+
252
+ export default defineConfig({
253
+ release: { defaultBranch: "master" },
254
+ });
255
+ ```
256
+
257
+ The `build` section applies too: the checks and the verification build with the same entry, output and CSS settings as `opdk build`.
258
+
259
+ ## Flags
260
+
261
+ | Flag | Applies to | What it does |
262
+ |---|---|---|
263
+ | `--tag <name>` | `check` | Compare the tag with the version. Defaults to `GITHUB_REF_NAME` when `GITHUB_REF_TYPE=tag` |
264
+ | `--no-build` | `check`, `<bump>` | Skip `build`, `assets` and `reproducible` |
265
+ | `--no-reproducible` | `check`, `<bump>` | Build once |
266
+ | `--no-api` | `check`, `<bump>` | Skip the API check |
267
+ | `--no-test` | `<bump>` | Do not run the plugin's `npm test` before the bump |
268
+ | `--dry-run` | `<bump>` | Run everything but the commit, the tag and the pushes; print the diff; restore the files. Never calls `gh`; does fetch from and `ls-remote` `origin` |
269
+ | `--no-push` | `<bump>` | Stop at the local tag. Continue later with `opdk release publish` |
270
+ | `--timeout <minutes>` | `<bump>`, `publish` | How long to wait for the workflow once it started (default 20) |
271
+ | `--zip` | `<bump>`, `publish` | Expect `<id>-<version>.zip` among the release assets. The workflow must run with `zip: true` |
272
+
273
+ `--zip` and `--timeout` cannot be combined with `--no-push`.
274
+
275
+ `gh` and `git` are run with argument arrays. Only the git commands that talk to the remote (`fetch`, `ls-remote`, `push`) get `GIT_TERMINAL_PROMPT=0` and, unless `GIT_SSH_COMMAND`, `GIT_SSH` or `core.sshCommand` is set, `GIT_SSH_COMMAND="ssh -o BatchMode=yes"`; `gh` gets `GH_PROMPT_DISABLED=1`. Nothing waits for a prompt. `OPDK_DEBUG=1` prints a stack for an unexpected error.
276
+
277
+ ## Rollback
278
+
279
+ A bad release is fixed by a new patch version. `opdk release` never moves or deletes a tag and has no force flag. A public release is not deleted either: if its assets are wrong, release a new version and let Obsidian pick that up from `manifest.json`.
280
+
281
+ ## Example output
282
+
283
+ A successful run of `opdk release patch`:
284
+
285
+ ```text
286
+ · test npm test (--no-test skips it)
287
+ ✓ test npm test passed
288
+ · bump my-plugin: 0.2.1 -> 0.2.2
289
+ ✓ bump package.json updated
290
+ ✓ bump package-lock.json updated
291
+ ✓ bump manifest.json updated
292
+ ✓ bump versions.json updated
293
+ ✓ bump CHANGELOG.md updated
294
+ · check my-plugin 0.2.2
295
+ ✓ check versions: manifest.json, package.json and package-lock.json are all 0.2.2
296
+ ✓ check versions.json: 0.2.2 maps to 1.5.0
297
+ ✓ check manifest: manifest.json follows the directory's rules
298
+ ✓ check changelog: CHANGELOG.md has a section for 0.2.2
299
+ ✓ check kit: the kit is v0.1.0 (6e33ca4) in package.json, package-lock.json, 2 workflow lines
300
+ ✓ check build: production build of src/main.ts: main.js 0.7 KiB, free of Node-only references
301
+ ✓ check assets: main.js, manifest.json, styles.css (built)
302
+ ✓ check reproducible: main.js, styles.css identical byte for byte between the working-tree build and a build of the committed tree (HEAD 4e22a12) extracted to another folder
303
+ ✓ check api: 1 bundled source file(s) use nothing newer than minAppVersion 1.5.0
304
+ ✓ check my-plugin 0.2.2: ready to release.
305
+ ✓ git committed "chore(release): 0.2.2" and created the annotated tag 0.2.2
306
+ · git tag 0.2.2 at 44921bb, branch main
307
+ ✓ gh you/my-plugin: signed in, admin access
308
+ ✓ git pushed the tag 0.2.2 (only the tag; the branch waits for the release)
309
+ · wait Release run 43039645752: in_progress https://github.com/you/my-plugin/actions/runs/43039645752
310
+ · wait Release run 43039645752: queued
311
+ · wait Release run 43039645752: in_progress
312
+ · wait Release run 43039645752: completed (success)
313
+ ✓ wait Release succeeded in 1 min
314
+ ✓ verify assets: main.js, manifest.json, styles.css
315
+ ✓ verify release notes equal the CHANGELOG section of 0.2.2
316
+ ✓ verify main.js, manifest.json, styles.css equal a local build of 0.2.2 (44921bb) byte for byte
317
+ ✓ verify attestations: main.js, manifest.json, styles.css verified for you/my-plugin at 0.2.2
318
+ ✓ release 0.2.2 is public and the latest release: https://github.com/you/my-plugin/releases/tag/0.2.2
319
+ ✓ git pushed the release commit to main (no force)
320
+ ✓ release you/my-plugin 0.2.2 released
321
+ · release release https://github.com/you/my-plugin/releases/tag/0.2.2
322
+ · release workflow https://github.com/you/my-plugin/actions/runs/43039645752
323
+ · release branch main pushed; Obsidian now reads 0.2.2 from its manifest.json
324
+ ```
325
+
326
+ ### A stop after the release is public
327
+
328
+ Someone pushed to `main` while the release ran, so `origin` rejects the push of the release commit. The release is already public and the output says how to finish (the git error is printed as git wrote it). When the server refuses the push instead (a branch protection, a repository rule or a server hook), the first line reads `origin refused the push of main (a branch protection, a repository rule or a server hook).` and the hint says to get the release commit onto the branch the way the rule allows, because pulling will not help:
329
+
330
+ ```text
331
+ ✗ release 0.2.3: origin rejected the push of main: it has commits that are not here. The release 0.2.3 is already public.
332
+ git push origin 44921bb:refs/heads/main failed: To github.com:you/my-plugin.git
333
+ ! [rejected] 44921bb -> main (fetch first)
334
+ error: failed to push some refs to 'github.com:you/my-plugin.git'
335
+ Merge them without rewriting the release commit: `git pull --no-rebase origin main`, then `git push origin main`. The manifest on main must reach the version 0.2.3 for Obsidian to offer it.
336
+ ✗ release stopped while pushing the branch.
337
+ The release 0.2.3 is public.
338
+ The branch main was not pushed.
339
+ Resume with: opdk release publish 0.2.3
340
+ ```
341
+
342
+ ## Migrating from a plugin's own release scripts
343
+
344
+ What the kit replaces is usually the same; what stays is your own.
345
+
346
+ **The release scripts and workflow:**
347
+
348
+ - A version-sync script (`scripts/version-sync.cjs`) is replaced by `opdk release <bump>`, which also refuses to rewrite a released `versions.json` entry and checks the lockfile.
349
+ - A version assertion script (`scripts/assert-versions.cjs`) is replaced by `opdk release check`. If the script never compared the tag with the manifest, the workflow now does.
350
+ - A zip script (`scripts/make-zip.cjs`) goes away, and so does a release audit script (`scripts/release-audit.cjs`). No release ships a zip by default, so there is nothing to audit; the draft is verified against a build of the tag instead, and `--zip` exists if you want a zip. If you had added an attestation after a scorecard flagged its absence, it is now made, and verified, by the flow.
351
+ - `.github/workflows/release.yml` becomes the short caller from Quick start.
352
+ - `scripts.build` has to run `opdk build`.
353
+ - What changes: the release is created as a draft and published by `opdk release` after verification, its body is the CHANGELOG section instead of GitHub's list of pull requests, the workflow no longer runs `npm run test` (a release workflow that ran only that and `npm run build` loses the test run; run tests, lint and typecheck in branch CI and in your own `release:check` script before you cut the release), and the branch is pushed after the release instead of with the tag. The tag is annotated, which is new if your tags were lightweight. The release commit still goes straight to the default branch, so a protection rule that blocks that push ends the flow at its last step (see the table of stops).
354
+ - If you keep your own schema version policy or an "instructions review" gate, run them before `opdk release`, because the release needs a clean tree. If generated files name the plugin version and your CI checks them in sync (`build:skill -- --check`), the release commit holds only the version files, so after `opdk release` regenerate them and commit the result, or CI fails. A GitHub Pages workflow on the same tag keeps working; the release wait ignores it.
355
+
356
+ **In `ci.yml` and `package.json`** (if your `ci.yml` runs `node scripts/assert-versions.cjs`, `npm run release:zip` and uploads `<plugin>-*.zip` with the bundle):
357
+
358
+ - Replace the `node scripts/assert-versions.cjs` step with `npx opdk release check --no-build --no-api`. Branch CI already installs and runs `npm run build` as a step of its own, so `--no-build` skips the build, asset and reproducibility checks, which would build twice more, and `--no-api` skips the `minAppVersion` check against the Obsidian API, which needs a type-aware lint pass. What stays: the version files agree, `versions.json`, the manifest rules, the CHANGELOG section and the format of the JSON files the release rewrites. The full check (build, assets, reproducibility, API) runs in the release workflow on the tag and in `opdk release <bump>` before anything is committed. Drop both flags to run the full check in branch CI as well, at the price of the two extra builds and the type-aware pass. The kit's reusable [`plugin-ci.yml`](ci.md) runs this step with the flags above, together with lint, typecheck, tests, the scanner and the build.
359
+ - Remove the `Pack plugin zip` step (`npm run release:zip`) and the `<plugin>-*.zip` line from the artifact `path:` list.
360
+ - In `package.json`, rewrite `release:check` by replacing `node scripts/version-sync.cjs` with `opdk release check` (it builds, so a trailing `npm run build` is redundant), and remove `release:zip`, `release` and `release:audit` if you have them. `release:check` keeps your own steps (scorecard and tests, and lint and typecheck if it ran them).
361
+
362
+ **If the plugin has no `versions.json`:**
363
+
364
+ - Create `versions.json` before the first `opdk release check`, in the format the kit writes (two-space indent, final newline), not on one line:
365
+
366
+ ```json
367
+ {
368
+ "1.7.1": "1.5.0"
369
+ }
370
+ ```
371
+
372
+ `opdk release <bump>` also creates a missing file, but `check` fails without it. `check` also fails on a one-line file, because the release rewrites it and refuses a file it cannot write back as it is. Prettier keeps a one-entry object on one line, so use the `node -e` command in the hint of that error (it writes LF line endings, so a CRLF file that is misformatted for another reason becomes LF).
373
+
374
+ **Existing tags:** legacy tags such as `v0.x` stay as they are. The kit looks for the exact tag it is releasing and never lists or touches other tags.
@@ -0,0 +1,204 @@
1
+ # Scanner
2
+
3
+ `opdk scan` runs, locally, the checks behind the Obsidian community plugin scanner's findings over your repository. Only the ESLint configuration is published upstream (in `eslint-plugin-obsidianmd`); the CSS and manifest checks reproduce findings seen on plugin listings. It exits 1 when a step has a finding: the scanner's ESLint warnings count as findings, advisory `!` lines do not. `obsidianPlugin()` is the ESLint config your plugin uses day to day, built on the same preset.
4
+
5
+ ![Terminal: opdk scan prints lint, css, code and meta with 0 findings each, then the summary and exit code 0](media/scan.gif)
6
+
7
+ ## Why
8
+
9
+ A plugin's public score dropped from 94% to 91% between 1.1.5 and 1.1.6. The cause was a `["forum", "obsidian", "md"].join(".")` workaround that the scanner reports as "Plugin assembles domain names at runtime from split/joined parts". Nothing local failed, so nobody saw it until the listing changed.
10
+
11
+ The first fix was a regex gate that guessed at the scanner's rules, and the guess was too narrow. When `eslint-plugin-obsidianmd` 0.5.1 came out, running its own scanner configuration over that plugin found seven warnings the gate had never seen, all in a folder the gate skipped. The listing's 24 CSS warnings came from files the old `!important` check never walked. `opdk scan` takes the guessing out: it runs the scanner's configuration itself, over the same files the scanner reads.
12
+
13
+ ## Quick start
14
+
15
+ Add the command to `package.json` and run it before every release:
16
+
17
+ ```json
18
+ {
19
+ "scripts": {
20
+ "scan": "opdk scan"
21
+ },
22
+ "devDependencies": {
23
+ "eslint": "^10.14.0",
24
+ "typescript": "^6.0.3",
25
+ "obsidian-plugin-dev-kit": "github:Dimagious/obsidian-plugin-dev-kit#v0.3.2"
26
+ }
27
+ }
28
+ ```
29
+
30
+ Replace `vX.Y.Z` with the latest tag and pin it exactly. `eslint` (`^9.19.0 || ^10.0.0`) and `typescript` (`>=6.0.0 <6.1.0`) are peer dependencies of the kit. The scan runs on the ESLint and the TypeScript your plugin installs, and it fails before linting when that TypeScript is older than 6: the community scanner type-checks with TypeScript 6, and 5.x hides some of its warnings (see "Differences from the public scorecard"). Run `npm install -D typescript@6` and fix what `tsc` then reports. TypeScript 7 is outside the range until typescript-eslint supports it, so a bare `npm install -D typescript` (which installs the newest) fails on the peer range: name the 6. On ESLint 10, npm may print `ERESOLVE overriding peer dependency` warnings that come from `eslint-plugin-obsidianmd`'s own dependencies; the install still succeeds, and `npm ls` exits 1 for the same reason. The kit cannot change this; if you want quieter installs, set `loglevel=error` in the plugin's `.npmrc`, which also hides other npm warnings. Add `eslint` to your own devDependencies explicitly: without it npm installs ESLint 9 on its own, because the plugins nested under `eslint-plugin-obsidianmd` peer on `^9`. The kit brings `eslint-plugin-obsidianmd` 0.5.1, `typescript-eslint`, `postcss`, `doiuse`, pinned, so remove your own copies once nothing else uses them; two copies of `typescript-eslint` are two parsers.
31
+
32
+ ```bash
33
+ git add -A # the scan reads what git tracks
34
+ npx opdk scan
35
+ ```
36
+
37
+ ## What it checks
38
+
39
+ It reads the files `git ls-files` lists in the plugin folder, minus symlinks (the scanner reads the repository's files, and a link may point outside it). Build output (`main.js`, `coverage/`, `.preview/`) is untracked, so the scanner never sees it and neither does the scan. A new file counts once it is staged.
40
+
41
+ Run it from the plugin root: `eslint-plugin-obsidianmd` reads `manifest.json` from the current directory when it loads.
42
+
43
+ | Step | What it runs | Notes |
44
+ |---|---|---|
45
+ | `lint` | The scanner's ESLint configuration over the tracked files it does not ignore: the `SCANNER_IGNORES` list in `src/scanner/scanner-config.ts`, upstream's 48 entries less the `e2e` folder, with `eslint` removed from the tool-config group (see "Differences from the public scorecard"). Notable ones: `**/*.cjs`, `**/*.mjs`, `**/*.cts`, `**/*.mts` (so config files and scripts in those formats are not linted), locale folders (`i18n`, `locale`, `translations`, `l10n`), mocks, `e2e-tests`, `*.e2e.*`, tests (`*.test.*`, `*.spec.*`, `test/`, `tests/`, `__tests__/`), `scripts/`, `docs/`, `.obsidian`, `test-vault`, `pkg`, `automation`, build output (`dist`, `build`, `main.js`) and `esbuild.config.mjs`. The root `eslint.config.js` and `eslint.config.ts` are linted, and so is the `e2e/` folder (except its `*.spec.*` files; see "Differences from the public scorecard"); `.mjs`, `.cjs`, `.mts` and `.cts` configs stay ignored by their extension globs. Every file that is not ignored gets the rules the preset applies to it; the test-setup files (`global-setup.*`, `*-global-setup.*`, `test-setup.*`, `setupTests.*`, `*.setup.*`) and the files in `e2e/` also get the runtime rules the preset exempts them from (see "Differences from the public scorecard") | The configuration is the one in `eslint-plugin-obsidianmd`'s docs, version 0.5.1 (see Credits). Every finding fails, warnings too: the scanner turns most rules into warnings and a warning still lowers the score. `@typescript-eslint/no-unsafe-*` and the two command-id rules are on, as in the scanner's newest layer (see "Differences from the public scorecard"). Type information comes from the plugin's TypeScript, which must be 6. A file no `tsconfig.json` covers is linted without type information, and its findings print as one advisory `!` line per file that does not fail the scan: the one scorecard compared lists none of them, which is an inference, not something the scanner's authors confirm (see "Differences from the public scorecard") |
46
+ | `css` | Every tracked `.css` file, parsed with PostCSS | `!important`, `:has()`, and features Obsidian's Chromium lacks or supports only partly, from caniuse data through `doiuse`, against Chrome 142 (Electron 39, the Chromium of Obsidian 1.11.4). Comments are parsed out, so prose cannot trip a rule |
47
+ | `code` | Two checks on the script files under `src/`, tests excluded. Unlike the lint step, this one does read `.mjs`, `.cjs`, `.mts` and `.cts` files under `src/` | A host assembled from joined strings (`["forum", "md"].join(".")`, `.join("/")`), which no ESLint rule covers. And `@ts-ignore`, `@ts-expect-error`, `@ts-nocheck`, printed as a warning that does not fail the scan: the scanner's configuration leaves `ban-ts-comment` off. The domain check strips JSDoc and line comments first, so prose does not count; the `@ts-` check reads the raw text, because the directives are comments |
48
+ | `meta` | `manifest.json` | The description must not start with the plugin name. The name comes from the manifest |
49
+
50
+ Findings print as `file:line rule message`, grouped by step and sorted by file and line.
51
+
52
+ ## Options
53
+
54
+ `opdk scan` takes no flags, and the `scan` section of `opdk.config.mjs` has no keys. Every file the scanner reads counts.
55
+
56
+ `scan.ignore` was removed. It skipped tracked files in every step, and what it skipped was still on the public scorecard: a plugin that listed `site/**` saw `opdk scan` pass while the scorecard showed 20 CSS warnings from `site/assets`. The scanner reads every tracked stylesheet and every script a tsconfig covers, and the exclusions that are known are built in (`SCANNER_IGNORES`, above). A config that still has the key fails with `"scan.ignore" was removed` before any check runs. To get a finding off the scorecard, fix it, or stop tracking the file (`git rm --cached`, or move it out of the repository). A script outside every tsconfig appears not to be read by the scanner (inferred from one scorecard, see "Differences from the public scorecard"), so `opdk scan` prints it as an advisory line and it needs no entry anywhere.
57
+
58
+ Two situations stop the scan before any check runs ("is not inside a git repository" or "no files to scan"), and each hint names its own fix. Not a git repository: run `git init` and `git add` the plugin's files, or run opdk from the plugin repository. A repository that tracks nothing in the folder: `git add` the files, or run opdk from the plugin repository.
59
+
60
+ ## One ESLint config for the plugin: `obsidianPlugin()`
61
+
62
+ Use the same preset in your own ESLint config, so `npm run lint` and `opdk scan` agree. Name the file `eslint.config.mjs`, not `.js`: the scanner installs the kit without building it, so a `.js` or `.ts` config that imports the kit gets two `no-unsafe-*` warnings there, and the scanner ignores `.mjs` files (see "Differences from the public scorecard"). `obsidianPlugin({ rootDir: import.meta.dirname })` works from `.mjs` as it does from `.js`:
63
+
64
+ ```js
65
+ // eslint.config.mjs
66
+ import { obsidianPlugin } from "obsidian-plugin-dev-kit/eslint";
67
+
68
+ export default [
69
+ ...obsidianPlugin({ rootDir: import.meta.dirname, ignores: ["site/**"] }),
70
+ ];
71
+ ```
72
+
73
+ It is `eslint-plugin-obsidianmd`'s `recommended` preset (which carries ESLint's core rules and typescript-eslint's `recommendedTypeChecked`) plus what three real plugins all added to it: `prefer-window-timers` and `settings-tab/prefer-setting-definitions` as errors, and unused arguments, variables and caught errors as errors unless they start with `_`. One more rule is an error that the preset does not have: a bare `window.<member>` (below). Run `eslint . --max-warnings=0` so the warnings the preset leaves count as well.
74
+
75
+ | Option | Type | Default | Meaning |
76
+ |---|---|---|---|
77
+ | `rootDir` | string | `process.cwd()` | Folder the tsconfig is looked up from. Pass `import.meta.dirname` so an editor that starts ESLint elsewhere finds it |
78
+ | `tsconfig` | string | `"./tsconfig.json"` | tsconfig for the type-aware rules, relative to `rootDir` |
79
+ | `ignores` | string[] | `[]` | ESLint globs added to `DEFAULT_IGNORES`, which the entry point also exports so a config can extend or print it. It is what three real plugins all left out of their own lint (the intersection of their lists): `node_modules/**`, `coverage/**`, `dist/**`, `main.js`, `scripts/**`, `src/**/*.test.ts`, `vitest.config.ts`, `e2e/**`, `e2e-vault.pristine/**`, `playwright.config.ts`, `.obsidian-unpacked/**`, `design/**`. Paths only some plugins have (`site/**`, `.preview/**`, `src/test/**`, `tools/**`) go in your own `ignores` |
80
+
81
+ **Bare `window`.** A plain `window` is the main window; code that runs in a popout window must use `activeWindow`. The preset reports `window.addEventListener`, `window.innerWidth`, `window?.x` and `window["x"]` through `no-restricted-syntax`, and lets `window.open` and the timer functions (`setTimeout`, `clearTimeout`, `setInterval`, `clearInterval`, `requestAnimationFrame`, `cancelAnimationFrame`) through, because `prefer-window-timers` asks for those on `window`. A handler parameter that is named `window` is reported too, although it is the popout's own window: `workspace.on("window-open", (win, window) => ...)` is typed that way by `obsidian.d.ts`, so rename the binding (`(win, popoutWindow) => popoutWindow.addEventListener(...)`). This is the kit's own rule: the community scanner does not report it (`prefer-active-doc` covers `document` only), so `opdk scan` does not check it either. To turn it off, add a block after the preset:
82
+
83
+ ```js
84
+ export default [
85
+ ...obsidianPlugin({ rootDir: import.meta.dirname }),
86
+ { files: ["**/*.ts"], rules: { "no-restricted-syntax": "off" } },
87
+ ];
88
+ ```
89
+
90
+ **`require()`.** The preset leaves `@typescript-eslint/no-require-imports` off, like upstream: `obsidianmd/no-nodejs-modules` already checks Node `require()`, and a bundled local `require("./x")` is not a phone problem. A plugin that wants the rule adds it in its own config:
91
+
92
+ ```js
93
+ { files: ["**/*.ts"], rules: { "@typescript-eslint/no-require-imports": "error" } },
94
+ ```
95
+
96
+ The right fix for a Node module on mobile is a dynamic `import()` (or `require()`) guarded by `Platform.isDesktop`, never a static import of a Node module.
97
+
98
+ If the plugin sets `no-restricted-syntax` itself in a later block, that setting replaces the kit's selector; repeat the selector (`BARE_WINDOW_SELECTOR` is exported from `obsidian-plugin-dev-kit/eslint`) next to your own if you want both. A bare `window` that is not a member access (`const w = window`) is not reported.
99
+
100
+ Do not enable `@typescript-eslint/no-misused-promises` next to it: the preset replaces it with `obsidianmd/no-misused-promises`, which does not count Obsidian's chaining `then` (every `Setting` chain) as a Promise. The preset reads ESLint's core rules from the ESLint resolved next to `eslint-plugin-obsidianmd`. `no-useless-assignment` and `preserve-caught-error` exist in ESLint 9.39 but only ESLint 10 added them to `recommended`, so on 9 enable them yourself.
101
+
102
+ The import lives under `/eslint`, not in the package root, so reading `opdk.config.mjs` does not load the lint plugins. `opdk scan` itself loads ESLint, `eslint-plugin-obsidianmd` and `doiuse` only when it runs, so `opdk --help`, `opdk build` and the other commands start without them and without reading `manifest.json` through the plugin.
103
+
104
+ ### ESLint 9 nested under eslint-plugin-obsidianmd
105
+
106
+ If the root has ESLint 10 and `node_modules/eslint-plugin-obsidianmd/node_modules/eslint` is a 9.x (seen in real plugin trees), the preset's core rules come from the nested 9, which lacks `preserve-caught-error`, `no-useless-assignment` and `no-unassigned-vars`. Nothing fails; the rules are just missing. `opdk scan` prints a `!` line naming both versions when the majors differ. Removing the plugin's own, older `eslint-plugin-obsidianmd` devDependency stays the first migration step (drop `typescript-eslint`, `@eslint/js` and `esbuild` at the same time if nothing else uses them), but it is not always enough: one plugin still had a nested 9 after it, another did not. The fix is to add `"overrides": { "eslint": "$eslint" }` to `package.json` and run `npm install` again; check with `npm explain eslint`. `npm dedupe` cannot remove the copy, because `@microsoft/eslint-plugin-sdl`, `eslint-plugin-import` and `eslint-plugin-react` peer on ESLint 9. The alternative is a `js.configs.recommended` block in your own `eslint.config.js`, which needs `@eslint/js` kept or added back.
107
+
108
+ ## Example output
109
+
110
+ A plugin that passes (the GIF above):
111
+
112
+ ```text
113
+ $ opdk scan
114
+ · scan hello-plugin: 4 tracked files
115
+ ✓ lint 0 findings (2 files, eslint-plugin-obsidianmd 0.5.1, typescript 6.0.3)
116
+ ✓ css 0 findings (1 file)
117
+ ✓ code 0 findings (1 file)
118
+ ✓ meta 0 findings (manifest.json)
119
+ ✓ scan hello-plugin: 0 findings in 4 tracked files
120
+ ```
121
+
122
+ The joined-domain regression again, plus a bare timer, an `!important` and a description that starts with the plugin name:
123
+
124
+ ![Terminal: opdk scan prints one failing finding under each of lint, css, code and meta, then the summary, and the exit code is 1](media/scan-fails.gif)
125
+
126
+ ```text
127
+ $ opdk scan
128
+ · scan hello-plugin: 4 tracked files
129
+ ✗ lint 1 finding (2 files, eslint-plugin-obsidianmd 0.5.1, typescript 6.0.3):
130
+ src/main.ts:3 obsidianmd/prefer-window-timers Use 'window.setTimeout()' instead of 'setTimeout()' for popout window compatibility.
131
+ ✗ css 1 finding (1 file):
132
+ styles.css:1 css-no-important `!important` is a scanner warning. Raise the selector's specificity instead.
133
+ ✗ code 1 finding (1 file):
134
+ src/main.ts:1 no-domain-assembly Domain or URL assembled from array.join(): the scorecard flags it as evasion. Use a string literal.
135
+ ✗ meta 1 finding (manifest.json):
136
+ manifest.json:1 manifest-description-no-name-prefix The description must not start with the plugin name. Current: "Hello is a demo plugin."
137
+ ✗ scan hello-plugin: 4 findings, each one lowers the community scorecard.
138
+ Fix them and rerun `opdk scan`. Each line reads file:line rule message.
139
+ $ echo "exit code: $?"
140
+ exit code: 1
141
+ ```
142
+
143
+ An advisory finding prints as a `!` line and leaves the exit code alone. So does a script no tsconfig covers (here a site script with 36 findings, none of them on the scorecard compared):
144
+
145
+ ```text
146
+ ! lint site/assets/site.js:5 outside-tsconfig 36 lint findings in a file no tsconfig covers (first: obsidianmd/prefer-active-doc). The scorecard compared did not list files outside every tsconfig project (inferred from one scorecard), and would if a tsconfig covered this one.
147
+ ✓ lint 0 findings (33 files, eslint-plugin-obsidianmd 0.5.1, typescript 6.0.3, 1 outside every tsconfig, advisory)
148
+ ✓ css 0 findings (4 files)
149
+ ! code src/stub.ts:1 ts-suppression TypeScript suppression directive: prefer augmenting Obsidian's types in the plugin.
150
+ ✓ code 0 findings (2 files)
151
+ ```
152
+
153
+ ## Differences from the public scorecard
154
+
155
+ - **Layers.** The scanner keeps layers by submission date. Upstream's docs say the older ones switch `@typescript-eslint/no-unsafe-*` and the command-id rules off, and the newest has them back at `warn`. A plugin's public scorecard (version 1.7.1) lists them, so the kit runs the newest layer: a clean scan here is clean in the older layers too. Before this, `opdk scan` missed those warnings.
156
+ - **`eslint.config.js` and `.ts`.** The kit lints them (only these two; `.mjs`, `.cjs`, `.mts` and `.cts` configs stay ignored by the extension globs), with type information, as the live scanner does. That plugin's 1.7.1 scorecard has four `no-unsafe-*` warnings in its root `eslint.config.js` (lines 14 to 17, `any` from an untyped helper), although `eslint-plugin-obsidianmd` 0.5.1's documented ignore list contains `**/eslint.config.*`. The kit follows the live scanner over the 0.5.1 text here (owner decision, 2026-11-11): `eslint` is removed from that ignore entry and the project service has `allowDefaultProject: ["eslint.config.*"]`. A config that the plugin's tsconfig already covers is linted with types through that tsconfig instead (typescript-eslint refuses a file that is both). `opdk scan` on that version reports the same four. Fix them in the file or type the helper.
157
+ - **A plugin's `eslint.config.js` that imports the kit.** The scanner appears to install a plugin's dependencies without running install scripts, so the kit, which builds `dist/` in `prepare`, has nothing to resolve there. One plugin's 1.7.2 `eslint.config.js` calls `obsidianPlugin()` from `obsidian-plugin-dev-kit/eslint` on line 9, and its scorecard has exactly one `no-unsafe-call` and one `no-unsafe-assignment` (the spread of the result) beyond the other findings. `opdk scan` lints every script that imports `obsidian-plugin-dev-kit` from text where that package does not exist, which reproduces both, and the two findings carry a hint to rename the file (for a file that is not an `eslint.config.*`, the hint says to keep it out of every tsconfig instead). The cause is inferred from that one scorecard, and from deleting the kit's `dist/eslint` in a copy of the plugin; the scanner's authors have not confirmed it. The fix is to name the config `eslint.config.mjs`: the scanner ignores `**/*.mjs`, so the file is not linted, and `obsidianPlugin({ rootDir: import.meta.dirname })` works from it. A block `eslint-disable` comment for the two rules is not a fix: it fails the plugin's own lint (unused directive and `eslint-comments/disable-enable-pair`), and `opdk scan` then reports `disable-enable-pair` instead.
158
+ - **Files outside every tsconfig.** The kit used to lint them without type information and fail on the findings. A plugin's `site/assets/site.js` (not in any tsconfig) had 36 findings that way (`prefer-active-doc` 27, `no-restricted-globals` 2, `no-unsanitized/property` 2, `sdl/no-inner-html` 2, `no-unused-vars` 2, `prefer-window-timers` 1), and the plugin's public scorecard has none of them, while it lists the 20 CSS warnings of the same folder. So the scan now prints them as one advisory line per file and does not fail. This is inferred from that single comparison, not confirmed by the scanner's authors (the other explanation, a scanner exclusion for `assets/` or site scripts, fits it too). If a tsconfig covers such a file, the scan reports it as a failing finding.
159
+ - **Test-setup files: `global-setup.*`, `*-global-setup.*`, `test-setup.*`, `setupTests.*`, `*.setup.*`.** `eslint-plugin-obsidianmd` exempts test files from `no-nodejs-modules` and the other Obsidian-runtime rules, but the scanner's ignore list does not name these. One plugin's `integration/global-setup.ts` imports `node:fs`, `node:path` and `node:url` and its scorecard has three `no-nodejs-modules` warnings for them. That is the only evidence; the other four names are the same family in the preset's own list and are inferred from it, not seen on a scorecard. The kit lifts the exemption for exactly these patterns (`SETUP_FILE_PATTERNS`, `withoutRuntimeExemptions`). Everything else the preset exempts stays exempt, because nothing shows the scanner reports it: worker files (`*.worker.*`, `*-worker.*`, `*_worker.*`, `workers/**`; a Worker has no `activeWindow`, so `prefer-window-timers` and `no-global-this` would be wrong advice there), the `test-helpers`, `test-support` and `test-utils` folders, `*.testing.*`, `testUtils*`, and tool configs and scripts. A file the scanner's own list names stays out of the scan.
160
+ - **The `e2e/` folder.** Upstream ignores `**/e2e/**` and the preset exempts it from the Obsidian-runtime rules, but the live scanner lints the files in `e2e/` that a `tsconfig.json` covers. A plugin's 1.1.0 scorecard listed nothing from `e2e/`; its 1.1.1 added `e2e/tsconfig.json` (extends the root one, includes `./**/*.ts`) and the scorecard then lists 21 findings in `e2e/fixtures.ts`, `e2e/demo-*.ts` and `e2e/live-key.ts`: the `no-unsafe-*` warnings and also `prefer-window-timers`, `no-global-this` and `no-nodejs-modules`. It has no `prefer-active-doc` for the one `document.querySelector` in `e2e/fixtures.ts` (inside a callback passed to Playwright's `evaluate`, next to a `setTimeout` in the same callback that is reported), so that rule stays off for `e2e/` (`E2E_EXEMPT_RULE`); it is not known whether the scanner exempts the rule in the folder, skips `document` inside such a callback, or does not report `prefer-active-doc` on any file a tsconfig covers (no scorecard seen shows it on one). `*.spec.*` files in the folder are not listed. Another plugin keeps its e2e helpers in a root `tsconfig.e2e.json`, which the project service does not read (it finds `tsconfig.json` only); its scorecard has none of them, which fits the rule that a file outside every tsconfig is not reported. So `opdk scan` lints `e2e/` like any folder and lifts the preset's runtime exemption for it (`E2E_FILE_PATTERNS`), while `*.spec.*` stays ignored. `e2e-tests/` and `*.e2e.*` stay ignored and exempt: no scorecard shows a plugin with either. Your own `npm run lint` keeps `e2e/**` in `obsidianPlugin()`'s default ignores, so it will not show these findings. If a plugin's scan now fails on `e2e/`, either fix the runtime findings in the code (a `window.setTimeout`, `activeWindow`) or keep e2e type-checking out of `tsconfig.json`: move it to a root `tsconfig.e2e.json` and point the e2e type-check at it. The `no-unsafe-*` findings (14 of the 21) are not code problems: they come from the imports of the kit (`createObsidianTest`, `obsidian.evaluate`, `obsidian.replace`), which the scanner cannot resolve because it installs the kit without building it, so typing the `evaluate` result does not remove them and only the tsconfig move does. Their hint says so, and a second scorecard supports the "kit not built" inference of the entry above. This is inferred from two scorecards, not confirmed by the scanner's authors.
161
+ - **`esModuleInterop` and `moment`.** `opdk scan` type-checks with TypeScript 6 and the plugin's own compiler options. The cause of the gap is `esModuleInterop`: TypeScript 6 forces it on, and TypeScript 5 with `esModuleInterop: true` behaves the same. Under it the namespace import of an `export =` module is not callable, and `obsidian`'s typings declare `moment` that way (`export const moment: typeof Moment`, with `Moment` from `import * as Moment from 'moment'`). A call such as `moment(date).format("YYYY-MM-DD")` with `moment` imported from `obsidian` is therefore TS2349 ("This expression is not callable") in the plugin's own `tsc --noEmit`, and `no-unsafe-call`, `no-unsafe-member-access` and `no-unsafe-return` warnings in the scan. A plugin on TypeScript 5 without `esModuleInterop` gets neither. Checked on a minimal project with `obsidian` 1.14.4 and `moment` 2.31.0:
162
+
163
+ | TypeScript | `esModuleInterop` | `moment(...)` from `obsidian` |
164
+ |---|---|---|
165
+ | 5.9.3 | unset or `false` | compiles |
166
+ | 5.9.3 | `true` | TS2349 |
167
+ | 6.0.3 | unset (forced on) | TS2349 |
168
+ | 6.0.3 | `false` with `ignoreDeprecations: "6.0"` | compiles |
169
+ | 6.0.3 | `false` | TS5107 (the option is deprecated), no type check |
170
+
171
+ The public scorecard of one plugin (1.7.1) lists exactly these three on such a line although `moment` was a devDependency, and `opdk scan` with the plugin's TypeScript 5.9 reported 0 there. So the live scanner very likely runs TypeScript 6 (inferred from this symptom, not confirmed). `opdk scan` therefore needs TypeScript 6 in the plugin: it reads the version typescript-eslint resolves and, on 5.x or older, fails before linting with a `✗ scan` line that says to run `npm install -D typescript@6`; with no TypeScript installed it fails the same way. It prints the version it used in the `lint` line (`typescript 6.0.3`). The plugin's own `tsc` then reports the same TS2349 on `moment`, which is where to fix it.
172
+
173
+ The plugin has to fix the call, not the scan. The fix is to type it instead of relying on the `obsidian` typing:
174
+
175
+ ```ts
176
+ import { moment } from "obsidian";
177
+
178
+ interface MomentLike {
179
+ format(pattern: string): string;
180
+ }
181
+ const toMoment = moment as unknown as (input: Date) => MomentLike;
182
+ ```
183
+
184
+ Under TypeScript 6 this scans clean.
185
+ - **`obsidianmd/ui/sentence-case`.** Off here and on the scorecard. Upstream's docs list "the three sentence-case rules" among the rules the scanner disables for every layer, and the newest layer's additions do not include them. A plugin that wants the check turns it on itself, as in `eslint-plugin-obsidianmd`'s "Upgrading to 0.5.0" section ("`ui/sentence-case` is off"): `{ rules: { "obsidianmd/ui/sentence-case": ["warn", { enforceCamelCaseLower: true }] } }`.
186
+ - **The kit can be stricter.** It uses the `recommended` set of the ESLint that runs it, and ESLint 10 adds `preserve-caught-error` and `no-useless-assignment` to it; it also reports the `moment` ban (`depend/ban-dependencies`). On that version these three are not on the public scorecard, so `opdk scan` reports 12 findings there against the scorecard's 9.
187
+ - **Partly supported CSS.** `css-browser-feature/*` findings are real: the public scorecard reports "partially supported" features too (`text-decoration: underline dotted ...`, for one plugin). Only bare `underline` and `none` pass.
188
+ - **Browser target.** The scorecard names an Obsidian version per plugin: "Obsidian 1.4.5" for a plugin with `minAppVersion` 1.5.0 and "Obsidian 1.11.4" in listings of plugins with `minAppVersion` 1.13.0. How the scanner maps a plugin to a version is not documented, so the kit checks one target, Chrome 142 (Obsidian 1.11.4). A feature that only an older Chromium lacks can appear on the scorecard of a plugin with a low `minAppVersion` and not here.
189
+ - **Parity, measured.** `opdk scan` on the release tags of three plugins gives the counts per message that their public scorecards list (read on 2026-11-13): 8 warnings, 20 and 0. The scorecard tab of a listing is rendered in the browser, so it cannot be fetched by a script; any later comparison is by hand.
190
+
191
+ ## Reading a failure
192
+
193
+ - The `✗` lines and their findings go to stderr, the `✓ · !` lines to stdout, and the exit code is 1 on any failing finding. Do not parse the text; use the exit code.
194
+ - A rule such as `obsidianmd/prefer-active-doc` is documented in `eslint-plugin-obsidianmd`. Fix the code, or add a disable comment with a description (the scanner honours them).
195
+ - `css-browser-feature/<name>` names the caniuse feature. "Partially supported" means Chrome 142 has it with gaps; read the caniuse notes for that feature before keeping it.
196
+ - `parse-error` means ESLint could not read the file. Fix the syntax, or stop tracking the file if it is not plugin code.
197
+ - `outside-tsconfig` (a `!` line) is a file no tsconfig covers; the scorecard compared lists none of its findings (an inference from one scorecard) and they do not fail the scan.
198
+ - `css-syntax` means PostCSS could not parse a stylesheet.
199
+
200
+ When `eslint-plugin-obsidianmd` is bumped, the mirrored configuration has to be diffed again: a test pins the version it was taken from, so a bump fails the kit's tests until someone does.
201
+
202
+ ## Origin
203
+
204
+ The ESLint configuration in `opdk scan` mirrors "Community plugin scanner configuration" in `eslint-plugin-obsidianmd` 0.5.1 (`docs/configuration.md`), with the differences listed at the top of `src/scanner/scanner-config.ts`. The ignored paths are upstream's 48 less the `e2e` folder, with `eslint` removed from the tool-config group (see "Differences from the public scorecard"); its first three (`main.js`, `**/*.min.js`, `**/{dist,build,out,release}/**`) are its stand-ins for bundled output, and upstream says to drop `main.js` for a plugin written in JavaScript. The CSS, host and manifest checks follow the ones a plugin's own scorecard script grew on 2026-11-09.