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

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,88 @@
1
+ import { errorProblem, warningProblem } from "./problems.js";
2
+ import { asRecord, findFormatIssue } from "./json.js";
3
+ import { compareVersions, isSemver } from "./semver.js";
4
+ const GROUP = "versions.json";
5
+ /**
6
+ * The versions.json rules. The format check is the official action's (`validateVersionsJson` in
7
+ * obsidianmd/obsidian-workflows `src/manifest.ts`: an object of semver keys to semver values), with two more that
8
+ * the directory relies on: the current version maps to the manifest's `minAppVersion`, and `minAppVersion` never
9
+ * goes down as plugin versions go up (Obsidian installs the newest version an old app can run, and a lower
10
+ * mapping on a newer version would hand it a build that needs a newer app).
11
+ *
12
+ * Deviations from the action: a key or value that is not a version is a warning, as it is upstream (only the
13
+ * three rules above and the file itself being missing, invalid or not an object fail the check). Beyond upstream:
14
+ * a missing file is an error, because the directory relies on it, and the current-version and never-lower rules
15
+ * are errors.
16
+ */
17
+ export function checkVersionsJson(loaded, version, minAppVersion) {
18
+ if (loaded.kind === "missing") {
19
+ return [errorProblem(GROUP, "versions.json is missing.", missingHint(version, minAppVersion))];
20
+ }
21
+ if (loaded.kind === "invalid") {
22
+ return [errorProblem(GROUP, `versions.json is not valid JSON: ${loaded.message}.`, "Fix the syntax.")];
23
+ }
24
+ const versions = asRecord(loaded.value);
25
+ if (versions === undefined) {
26
+ return [errorProblem(GROUP, "versions.json must be an object mapping plugin versions to minimum app versions.", `Write { "${version}": "1.5.0" }.`)];
27
+ }
28
+ const problems = [];
29
+ // `opdk release <bump>` rewrites this file and refuses one it cannot write back as it is: say so before release day.
30
+ const issue = findFormatIssue(loaded.text, loaded.value, "versions.json");
31
+ if (issue !== undefined) {
32
+ problems.push(errorProblem(GROUP, issue.message, issue.hint));
33
+ }
34
+ for (const [key, value] of Object.entries(versions)) {
35
+ if (!isSemver(key)) {
36
+ problems.push(warningProblem(GROUP, `key "${key}" is not a version like 1.2.3.`, "Remove or fix the entry."));
37
+ }
38
+ if (typeof value !== "string" || !isSemver(value)) {
39
+ problems.push(warningProblem(GROUP, `the value of "${key}" is not a version like 1.5.0.`, "Map each plugin version to the minimum Obsidian version as a string."));
40
+ }
41
+ }
42
+ problems.push(...checkCurrent(versions, version, minAppVersion), ...checkNeverLower(versions));
43
+ return problems;
44
+ }
45
+ /**
46
+ * The hint for a missing file: a `node -e` command that writes it in the format the release writes back (two-space
47
+ * indent, LF, final newline). It sits inside double quotes in the shell, so the script has no `$`, backtick, `!` or
48
+ * inner double quote. The file name and the values must never contain quotes; versions are validated semver, so they
49
+ * cannot.
50
+ */
51
+ function missingHint(version, minAppVersion) {
52
+ if (minAppVersion === undefined || !isSemver(version) || !isSemver(minAppVersion)) {
53
+ return "Create it next to manifest.json as an object that maps the plugin version to minAppVersion, written with JSON.stringify (two-space indent, final newline). `opdk release <patch|minor|major>` creates it too.";
54
+ }
55
+ const script = `require('fs').writeFileSync('versions.json', JSON.stringify({ '${version}': '${minAppVersion}' }, null, 2) + '\\n')`;
56
+ return `Create it next to manifest.json with \`node -e "${script}"\`. \`opdk release <patch|minor|major>\` creates it too.`;
57
+ }
58
+ function checkCurrent(versions, version, minAppVersion) {
59
+ if (minAppVersion === undefined) {
60
+ return [errorProblem(GROUP, `manifest.json has no minAppVersion, so ${version} cannot be mapped in versions.json.`, 'Add "minAppVersion" to manifest.json.')];
61
+ }
62
+ if (!Object.hasOwn(versions, version)) {
63
+ return [errorProblem(GROUP, `versions.json has no entry for ${version}.`, `Add "${version}": "${minAppVersion}" as a new line in the same format (two-space indent, one entry per line), or let \`opdk release <patch|minor|major>\` add it for a new release.`)];
64
+ }
65
+ const mapped = versions[version];
66
+ if (mapped !== minAppVersion) {
67
+ return [
68
+ errorProblem(GROUP, `versions.json maps ${version} to ${typeof mapped === "string" ? mapped : "a non-string"}, but manifest.json minAppVersion is ${minAppVersion}.`, "Make them equal. If this version is already released, change manifest.json: a released entry in versions.json stays as it is."),
69
+ ];
70
+ }
71
+ return [];
72
+ }
73
+ function checkNeverLower(versions) {
74
+ const entries = Object.entries(versions)
75
+ .filter((entry) => isSemver(entry[0]) && typeof entry[1] === "string" && isSemver(entry[1]))
76
+ .sort(([a], [b]) => compareVersions(a, b) ?? 0);
77
+ const problems = [];
78
+ let highest;
79
+ for (const [pluginVersion, minApp] of entries) {
80
+ if (highest !== undefined && (compareVersions(minApp, highest[1]) ?? 0) < 0) {
81
+ problems.push(errorProblem(GROUP, `${pluginVersion} needs Obsidian ${minApp}, lower than ${highest[1]} that ${highest[0]} needs.`, "minAppVersion should only go up as the plugin version goes up. Check which of the two entries is wrong."));
82
+ }
83
+ else if (highest === undefined || (compareVersions(minApp, highest[1]) ?? 0) > 0) {
84
+ highest = [pluginVersion, minApp];
85
+ }
86
+ }
87
+ return problems;
88
+ }
@@ -0,0 +1,44 @@
1
+ /** The fields of a GitHub Actions run (REST `GET /repos/{repo}/actions/runs`) that the release waits on. */
2
+ export interface WorkflowRun {
3
+ readonly id: number;
4
+ /** `queued`, `in_progress`, `completed`, ... */
5
+ readonly status: string;
6
+ /** Empty until the run is completed; then `success`, `failure`, `cancelled`, ... */
7
+ readonly conclusion: string;
8
+ readonly event: string;
9
+ readonly headSha: string;
10
+ /** For a tag push, the tag name: two tags on one commit share `head_sha` but not this. */
11
+ readonly headBranch: string;
12
+ readonly url: string;
13
+ readonly name: string;
14
+ readonly createdAt: string;
15
+ /** `referenced_workflows[].path`: the reusable workflows the run called, as `owner/repo/.github/workflows/file.yml@ref`. */
16
+ readonly referenced: readonly string[];
17
+ }
18
+ /**
19
+ * The kit's reusable workflow, which the plugin's tag workflow must call. A run of another workflow on the same tag
20
+ * (all three plugins also publish GitHub Pages on a tag push) is not the release run.
21
+ */
22
+ export declare const KIT_WORKFLOW_PATH = "Dimagious/obsidian-plugin-dev-kit/.github/workflows/release.yml";
23
+ /** One run from the REST API. Throws a message that names the problem when the shape is wrong. */
24
+ export declare function parseRun(value: unknown): WorkflowRun;
25
+ /** The runs from the JSON of `GET /actions/runs`. */
26
+ export declare function parseRuns(json: string): WorkflowRun[];
27
+ /** The REST path that lists the push runs on one commit. */
28
+ export declare const runsPath: (repo: string, commit: string) => string;
29
+ /** The REST path of one run. */
30
+ export declare const runPath: (repo: string, id: number) => string;
31
+ /** True when the run called the kit's release workflow (at any ref). */
32
+ export declare const callsKitWorkflow: (run: WorkflowRun) => boolean;
33
+ /**
34
+ * The run that belongs to the tag: a push run on exactly the tagged commit, for exactly this tag (`head_branch` is the
35
+ * tag name on a tag push; two tags on one commit share the commit and its runs), that called the kit's release
36
+ * workflow, the newest if it ran more than once. Other workflows on the same push (Pages, say) are not the release,
37
+ * and a manual re-run by someone else is not a push event.
38
+ */
39
+ export declare function pickRun(runs: readonly WorkflowRun[], commit: string, version: string): WorkflowRun | undefined;
40
+ export type RunOutcome = "waiting" | "success" | "failed";
41
+ /** `completed` with `success` is the only success; `completed` with anything else (cancelled, skipped, timed out) failed. */
42
+ export declare function runOutcome(run: WorkflowRun): RunOutcome;
43
+ /** A one-line description for the progress output. */
44
+ export declare const describeRun: (run: WorkflowRun) => string;
@@ -0,0 +1,71 @@
1
+ import { asRecord } from "./json.js";
2
+ /**
3
+ * The kit's reusable workflow, which the plugin's tag workflow must call. A run of another workflow on the same tag
4
+ * (all three plugins also publish GitHub Pages on a tag push) is not the release run.
5
+ */
6
+ export const KIT_WORKFLOW_PATH = "Dimagious/obsidian-plugin-dev-kit/.github/workflows/release.yml";
7
+ const text = (record, key) => {
8
+ const value = record[key];
9
+ return typeof value === "string" ? value : "";
10
+ };
11
+ /** One run from the REST API. Throws a message that names the problem when the shape is wrong. */
12
+ export function parseRun(value) {
13
+ const record = asRecord(value);
14
+ const id = record?.id;
15
+ if (record === undefined || typeof id !== "number") {
16
+ throw new Error(`GitHub returned a workflow run without an id: ${JSON.stringify(value)}`);
17
+ }
18
+ const referenced = Array.isArray(record.referenced_workflows)
19
+ ? record.referenced_workflows.flatMap((entry) => {
20
+ const path = asRecord(entry)?.path;
21
+ return typeof path === "string" ? [path] : [];
22
+ })
23
+ : [];
24
+ return {
25
+ id,
26
+ status: text(record, "status"),
27
+ conclusion: text(record, "conclusion"),
28
+ event: text(record, "event"),
29
+ headSha: text(record, "head_sha"),
30
+ headBranch: text(record, "head_branch"),
31
+ url: text(record, "html_url"),
32
+ name: text(record, "name"),
33
+ createdAt: text(record, "created_at"),
34
+ referenced,
35
+ };
36
+ }
37
+ /** The runs from the JSON of `GET /actions/runs`. */
38
+ export function parseRuns(json) {
39
+ const parsed = JSON.parse(json);
40
+ const runs = asRecord(parsed)?.workflow_runs;
41
+ if (!Array.isArray(runs)) {
42
+ throw new Error("GitHub did not return a workflow_runs list.");
43
+ }
44
+ return runs.map((entry) => parseRun(entry));
45
+ }
46
+ /** The REST path that lists the push runs on one commit. */
47
+ export const runsPath = (repo, commit) => `repos/${repo}/actions/runs?head_sha=${commit}&event=push&per_page=100`;
48
+ /** The REST path of one run. */
49
+ export const runPath = (repo, id) => `repos/${repo}/actions/runs/${String(id)}`;
50
+ /** True when the run called the kit's release workflow (at any ref). */
51
+ export const callsKitWorkflow = (run) => run.referenced.some((path) => path.startsWith(`${KIT_WORKFLOW_PATH}@`));
52
+ /**
53
+ * The run that belongs to the tag: a push run on exactly the tagged commit, for exactly this tag (`head_branch` is the
54
+ * tag name on a tag push; two tags on one commit share the commit and its runs), that called the kit's release
55
+ * workflow, the newest if it ran more than once. Other workflows on the same push (Pages, say) are not the release,
56
+ * and a manual re-run by someone else is not a push event.
57
+ */
58
+ export function pickRun(runs, commit, version) {
59
+ return runs
60
+ .filter((run) => run.event === "push" && run.headSha === commit && run.headBranch === version && callsKitWorkflow(run))
61
+ .sort((a, b) => b.createdAt.localeCompare(a.createdAt) || b.id - a.id)[0];
62
+ }
63
+ /** `completed` with `success` is the only success; `completed` with anything else (cancelled, skipped, timed out) failed. */
64
+ export function runOutcome(run) {
65
+ if (run.status !== "completed") {
66
+ return "waiting";
67
+ }
68
+ return run.conclusion === "success" ? "success" : "failed";
69
+ }
70
+ /** A one-line description for the progress output. */
71
+ export const describeRun = (run) => `${run.name === "" ? "workflow" : run.name} run ${String(run.id)}: ${run.status}${run.conclusion === "" ? "" : ` (${run.conclusion})`}`;
@@ -0,0 +1,41 @@
1
+ import type { Finding } from "./findings.js";
2
+ /** A file the checks read: its path relative to the plugin root (`/` separators) and its text. */
3
+ export interface SourceFile {
4
+ readonly path: string;
5
+ readonly text: string;
6
+ }
7
+ /** Whether a tracked file is plugin source for the `code` check: script files under `src/`, tests aside. */
8
+ export declare function isShippedSource(relativePath: string): boolean;
9
+ /**
10
+ * Blanks out comments so prose cannot trip a rule, keeping every newline so the
11
+ * line numbers still point at the right place.
12
+ *
13
+ * Per-line stripping was the previous approach and it could not see a JSDoc
14
+ * block: the inner lines carry neither `//` nor a complete block-comment pair, so
15
+ * a sentence ending in "leaves the document." counted as a violation.
16
+ *
17
+ * It is textual, not a parser: a `//` or a slash-star inside a string literal (a URL, a glob) starts a "comment"
18
+ * that blanks the rest of the line, or up to the next star-slash. The checks below can therefore miss a hit
19
+ * after such a literal; they never invent one.
20
+ */
21
+ export declare function stripComments(text: string): string;
22
+ /**
23
+ * Scorecard warning: "Plugin assembles domain names at runtime from split/joined parts."
24
+ *
25
+ * Triggered by patterns like `["forum", "obsidian", "md"].join(".")`: anything that reconstructs a URL host from
26
+ * string fragments. Flags `.join(".")` and `.join("/")` on an inline array literal of strings.
27
+ *
28
+ * False-positive risk: someone could use `.join(".")` on a legitimate non-URL list. The fix in that case is a
29
+ * different separator, or a name that makes the non-URL intent obvious. The check is line-based, so an array that
30
+ * spans lines is not seen.
31
+ */
32
+ export declare function checkDomainAssembly(file: SourceFile): Finding[];
33
+ /**
34
+ * `@ts-expect-error`, `@ts-ignore` and `@ts-nocheck` against Obsidian's API: prefer augmenting its types in the
35
+ * plugin. Advisory: the scanner's ESLint configuration leaves `ban-ts-comment` off, and nothing found shows the
36
+ * scorecard counts these, so they are printed but do not fail the scan. Reads the raw text, because the
37
+ * directives are comments.
38
+ */
39
+ export declare function checkTsSuppressions(file: SourceFile): Finding[];
40
+ /** Both checks over every shipped source file. */
41
+ export declare function checkCode(files: readonly SourceFile[]): Finding[];
@@ -0,0 +1,82 @@
1
+ const SOURCE_EXTENSION = /\.(?:[cm]?[jt]s|[jt]sx)$/;
2
+ // Tests, mocks and fakes never reach the bundle. A `preview/` folder is not on this list on purpose: the scanner
3
+ // reads it (eslint-plugin-obsidianmd 0.5.1 found seven warnings on one plugin's preview stand that the old gate skipped).
4
+ const UNSHIPPED_PATH = /(?:^|\/)(?:test|tests|__tests__|__mocks__|node_modules)\/|\.(?:test|spec)\.[^/]+$/;
5
+ /** Whether a tracked file is plugin source for the `code` check: script files under `src/`, tests aside. */
6
+ export function isShippedSource(relativePath) {
7
+ return relativePath.startsWith("src/") && SOURCE_EXTENSION.test(relativePath) && !UNSHIPPED_PATH.test(relativePath);
8
+ }
9
+ /**
10
+ * Blanks out comments so prose cannot trip a rule, keeping every newline so the
11
+ * line numbers still point at the right place.
12
+ *
13
+ * Per-line stripping was the previous approach and it could not see a JSDoc
14
+ * block: the inner lines carry neither `//` nor a complete block-comment pair, so
15
+ * a sentence ending in "leaves the document." counted as a violation.
16
+ *
17
+ * It is textual, not a parser: a `//` or a slash-star inside a string literal (a URL, a glob) starts a "comment"
18
+ * that blanks the rest of the line, or up to the next star-slash. The checks below can therefore miss a hit
19
+ * after such a literal; they never invent one.
20
+ */
21
+ export function stripComments(text) {
22
+ const blank = (match) => match.replace(/[^\n]/g, " ");
23
+ return text.replace(/\/\*[\s\S]*?\*\//g, blank).replace(/\/\/[^\n]*/g, blank);
24
+ }
25
+ const JOIN_DOT = /\[\s*["'][^"']+["'][\s\S]*?\]\s*\.\s*join\s*\(\s*["']\.["']\s*\)/;
26
+ const JOIN_SLASH = /\[\s*["'][^"']+["'][\s\S]*?\]\s*\.\s*join\s*\(\s*["']\/["']\s*\)/;
27
+ const TS_DIRECTIVE = /(?:\/\/|\/\*+)\s*@ts-(?:expect-error|ignore|nocheck)\b/;
28
+ /**
29
+ * Scorecard warning: "Plugin assembles domain names at runtime from split/joined parts."
30
+ *
31
+ * Triggered by patterns like `["forum", "obsidian", "md"].join(".")`: anything that reconstructs a URL host from
32
+ * string fragments. Flags `.join(".")` and `.join("/")` on an inline array literal of strings.
33
+ *
34
+ * False-positive risk: someone could use `.join(".")` on a legitimate non-URL list. The fix in that case is a
35
+ * different separator, or a name that makes the non-URL intent obvious. The check is line-based, so an array that
36
+ * spans lines is not seen.
37
+ */
38
+ export function checkDomainAssembly(file) {
39
+ const findings = [];
40
+ stripComments(file.text)
41
+ .split("\n")
42
+ .forEach((line, index) => {
43
+ if (JOIN_DOT.test(line) || JOIN_SLASH.test(line)) {
44
+ findings.push({
45
+ check: "code",
46
+ file: file.path,
47
+ line: index + 1,
48
+ rule: "no-domain-assembly",
49
+ message: "Domain or URL assembled from array.join(): the scorecard flags it as evasion. Use a string literal.",
50
+ });
51
+ }
52
+ });
53
+ return findings;
54
+ }
55
+ /**
56
+ * `@ts-expect-error`, `@ts-ignore` and `@ts-nocheck` against Obsidian's API: prefer augmenting its types in the
57
+ * plugin. Advisory: the scanner's ESLint configuration leaves `ban-ts-comment` off, and nothing found shows the
58
+ * scorecard counts these, so they are printed but do not fail the scan. Reads the raw text, because the
59
+ * directives are comments.
60
+ */
61
+ export function checkTsSuppressions(file) {
62
+ const findings = [];
63
+ file.text.split("\n").forEach((line, index) => {
64
+ if (TS_DIRECTIVE.test(line)) {
65
+ findings.push({
66
+ check: "code",
67
+ file: file.path,
68
+ line: index + 1,
69
+ rule: "ts-suppression",
70
+ message: "TypeScript suppression directive: prefer augmenting Obsidian's types in the plugin.",
71
+ advisory: true,
72
+ });
73
+ }
74
+ });
75
+ return findings;
76
+ }
77
+ /** Both checks over every shipped source file. */
78
+ export function checkCode(files) {
79
+ return files
80
+ .filter((file) => isShippedSource(file.path))
81
+ .flatMap((file) => [...checkDomainAssembly(file), ...checkTsSuppressions(file)]);
82
+ }
@@ -0,0 +1,3 @@
1
+ import type { Command } from "../cli/types.js";
2
+ export declare const scanCommand: Command;
3
+ export declare const scanCommands: readonly Command[];
@@ -0,0 +1,43 @@
1
+ import { loadConfig } from "../config/load-config.js";
2
+ import { readManifest } from "../config/manifest.js";
3
+ const scanUsage = `Usage: opdk scan
4
+
5
+ Runs the community plugin scanner's ESLint configuration, plus checks that reproduce
6
+ its CSS, source and manifest findings, over the files git tracks in the plugin
7
+ folder. The scanner's ESLint warnings count as findings and fail the scan; advisory
8
+ "!" lines (ts-suppression) do not:
9
+ lint the scanner's own ESLint configuration (eslint-plugin-obsidianmd)
10
+ css every .css file: !important, :has, features Obsidian's Chromium lacks
11
+ code checks the ESLint rules do not cover (domain assembly from joined strings)
12
+ meta manifest.json description must not start with the plugin name
13
+
14
+ Needs a git repository: build output (main.js, coverage/) is untracked, so the
15
+ scanner never sees it and neither does this. Stage new files with git add first.
16
+ Findings print as file:line rule message. Exit 1 on any failing finding.
17
+
18
+ The plugin name comes from manifest.json. There are no settings: every file the scanner reads counts.
19
+ `;
20
+ export const scanCommand = {
21
+ name: "scan",
22
+ summary: "Run the community plugin scanner's checks over the tracked files",
23
+ usage: scanUsage,
24
+ async run(args, ctx) {
25
+ if (args.length > 0) {
26
+ throw new Error(`"opdk scan" takes no arguments, got "${args.join(" ")}". Run "opdk scan --help".`);
27
+ }
28
+ const manifest = readManifest(ctx.cwd);
29
+ await loadConfig(ctx.cwd);
30
+ // Loaded here, not at the top: the scan pulls in ESLint, obsidianmd, typescript-eslint and doiuse, and
31
+ // obsidianmd reads manifest.json from the current directory at import. Every other command, and
32
+ // `opdk --help`, must not pay for that or fail on it.
33
+ // The scan's ESLint plugins load `typescript` at import: a missing one is reported before that import.
34
+ const { missingTypescriptPreflight } = await import("./typescript-gate.js");
35
+ const missing = missingTypescriptPreflight(manifest.id, ctx.reporter);
36
+ if (missing !== undefined) {
37
+ return missing;
38
+ }
39
+ const { runScan } = await import("./run.js");
40
+ return runScan({ cwd: ctx.cwd, manifest, reporter: ctx.reporter });
41
+ },
42
+ };
43
+ export const scanCommands = [scanCommand];
@@ -0,0 +1,7 @@
1
+ import type { ScanConfig } from "../config/types.js";
2
+ /**
3
+ * Checks and copies the `scan` section of `opdk.config.mjs`. It has no keys. `ignore` used to skip tracked files, and
4
+ * a skipped file hid findings that the public scorecard still shows, so it was removed; the error says what to do
5
+ * instead of only naming the key.
6
+ */
7
+ export declare function validateScanConfig(value: unknown, source: string): ScanConfig;
@@ -0,0 +1,25 @@
1
+ /**
2
+ * Checks and copies the `scan` section of `opdk.config.mjs`. It has no keys. `ignore` used to skip tracked files, and
3
+ * a skipped file hid findings that the public scorecard still shows, so it was removed; the error says what to do
4
+ * instead of only naming the key.
5
+ */
6
+ export function validateScanConfig(value, source) {
7
+ if (!isRecord(value)) {
8
+ throw new Error(`${source}: "scan" must be an object.`);
9
+ }
10
+ if (Object.hasOwn(value, "ignore")) {
11
+ throw new Error(`${source}: "scan.ignore" was removed. The community scanner reads every tracked stylesheet and, as far as one scorecard shows, every script a tsconfig covers, so a path listed there still lowers the scorecard while \`opdk scan\` stayed silent. Delete the key and fix what \`opdk scan\` reports, or untrack the file.`);
12
+ }
13
+ const unknown = Object.keys(value);
14
+ if (unknown.length > 0) {
15
+ throw new Error(`${source}: unknown key(s) in "scan": ${unknown.join(", ")}. The "scan" section has no keys.`);
16
+ }
17
+ return {};
18
+ }
19
+ function isRecord(value) {
20
+ if (typeof value !== "object" || value === null) {
21
+ return false;
22
+ }
23
+ const prototype = Object.getPrototypeOf(value);
24
+ return prototype === Object.prototype || prototype === null;
25
+ }
@@ -0,0 +1,26 @@
1
+ import type { Finding } from "./findings.js";
2
+ import type { SourceFile } from "./code-checks.js";
3
+ /**
4
+ * The Chromium that Obsidian 1.11.4 runs on (Electron 39, Chrome 142): the browser the scanner names in
5
+ * "Unexpected browser feature ... is only partially supported by Obsidian 1.11.4". Raise it, together with the
6
+ * mirrored scanner configuration, when the scanner names a newer Obsidian. The public scorecard names an Obsidian
7
+ * per plugin ("1.4.5" for a plugin with `minAppVersion` 1.5.0) and how it picks one is not documented, so this is one
8
+ * target for every plugin; docs/scanner.md lists the gap.
9
+ */
10
+ export declare const OBSIDIAN_BROWSERS: readonly string[];
11
+ export declare const OBSIDIAN_VERSION = "1.11.4";
12
+ /**
13
+ * Scorecard CSS, over the files given: the public scanner walks the whole repository, not only what ships in
14
+ * `styles.css`. On 2026-11-09 the listing reported three kinds of finding, and this check reproduces each:
15
+ *
16
+ * - "Avoid !important": any `!important` in a declaration.
17
+ * - "Avoid :has": any `:has(` in a selector, for its invalidation cost.
18
+ * - "Unexpected browser feature ... is (only partially) supported by Obsidian 1.11.4": caniuse data through
19
+ * doiuse, the library behind stylelint-no-unsupported-browser-features, against OBSIDIAN_BROWSERS. It matched
20
+ * the listing exactly: `text-decoration-line` and `text-decoration-thickness` (partial), `columns`,
21
+ * `column-gap` and `break-inside` (partial), `ui-monospace` (not supported).
22
+ *
23
+ * Comments are parsed out by PostCSS, so prose cannot trip a rule. A file PostCSS cannot parse is reported as a
24
+ * `css-syntax` finding instead of aborting the scan.
25
+ */
26
+ export declare function checkCss(files: readonly SourceFile[]): Promise<Finding[]>;
@@ -0,0 +1,63 @@
1
+ import doiuse from "doiuse";
2
+ import postcss from "postcss";
3
+ /**
4
+ * The Chromium that Obsidian 1.11.4 runs on (Electron 39, Chrome 142): the browser the scanner names in
5
+ * "Unexpected browser feature ... is only partially supported by Obsidian 1.11.4". Raise it, together with the
6
+ * mirrored scanner configuration, when the scanner names a newer Obsidian. The public scorecard names an Obsidian
7
+ * per plugin ("1.4.5" for a plugin with `minAppVersion` 1.5.0) and how it picks one is not documented, so this is one
8
+ * target for every plugin; docs/scanner.md lists the gap.
9
+ */
10
+ export const OBSIDIAN_BROWSERS = ["chrome 142"];
11
+ export const OBSIDIAN_VERSION = "1.11.4";
12
+ /**
13
+ * Scorecard CSS, over the files given: the public scanner walks the whole repository, not only what ships in
14
+ * `styles.css`. On 2026-11-09 the listing reported three kinds of finding, and this check reproduces each:
15
+ *
16
+ * - "Avoid !important": any `!important` in a declaration.
17
+ * - "Avoid :has": any `:has(` in a selector, for its invalidation cost.
18
+ * - "Unexpected browser feature ... is (only partially) supported by Obsidian 1.11.4": caniuse data through
19
+ * doiuse, the library behind stylelint-no-unsupported-browser-features, against OBSIDIAN_BROWSERS. It matched
20
+ * the listing exactly: `text-decoration-line` and `text-decoration-thickness` (partial), `columns`,
21
+ * `column-gap` and `break-inside` (partial), `ui-monospace` (not supported).
22
+ *
23
+ * Comments are parsed out by PostCSS, so prose cannot trip a rule. A file PostCSS cannot parse is reported as a
24
+ * `css-syntax` finding instead of aborting the scan.
25
+ */
26
+ export async function checkCss(files) {
27
+ const findings = [];
28
+ for (const file of files) {
29
+ const add = (rule, node, message) => {
30
+ findings.push({ check: "css", file: file.path, line: node.source?.start?.line ?? 1, rule, message });
31
+ };
32
+ let root;
33
+ try {
34
+ root = postcss.parse(file.text, { from: file.path });
35
+ }
36
+ catch (error) {
37
+ const line = error instanceof postcss.CssSyntaxError && error.line !== undefined ? error.line : 1;
38
+ const reason = error instanceof postcss.CssSyntaxError ? error.reason : String(error);
39
+ findings.push({ check: "css", file: file.path, line, rule: "css-syntax", message: `Cannot parse the file: ${reason}` });
40
+ continue;
41
+ }
42
+ root.walkDecls((declaration) => {
43
+ if (declaration.important) {
44
+ add("css-no-important", declaration, "`!important` is a scanner warning. Raise the selector's specificity instead.");
45
+ }
46
+ });
47
+ root.walkRules((rule) => {
48
+ if (rule.selector.includes(":has(")) {
49
+ add("css-no-has", rule, "`:has()` is a scanner warning. Mark the element with a class instead.");
50
+ }
51
+ });
52
+ await postcss([
53
+ doiuse({
54
+ browsers: OBSIDIAN_BROWSERS,
55
+ onFeatureUsage: (usage) => {
56
+ const support = usage.featureData?.partial !== undefined ? "only partially supported" : "not supported";
57
+ add(`css-browser-feature/${usage.feature}`, usage.usage, `"${usage.feature}" is ${support} by ${OBSIDIAN_BROWSERS.join(", ")} (the scanner's Obsidian ${OBSIDIAN_VERSION}).`);
58
+ },
59
+ }),
60
+ ]).process(file.text, { from: file.path });
61
+ }
62
+ return findings;
63
+ }
@@ -0,0 +1,16 @@
1
+ /** The major of a version such as `9.39.5` or `10.14.0`, or `undefined` for text that does not start with one. */
2
+ export declare function majorOf(version: string): number | undefined;
3
+ /**
4
+ * The warning for an ESLint next to `eslint-plugin-obsidianmd` that is another major than the one that runs, or
5
+ * `undefined` when they agree. The preset takes ESLint's core rules (`builtinRules`) from the ESLint it resolves
6
+ * from its own location, so a nested ESLint 9 under a root ESLint 10 leaves `preserve-caught-error`,
7
+ * `no-useless-assignment` and `no-unassigned-vars` out of `recommended` without any error.
8
+ */
9
+ export declare function describeEslintMismatch(running: string, nested: string): string | undefined;
10
+ /** The version of the `eslint` package that `eslint-plugin-obsidianmd` resolves, from the plugin's own location. */
11
+ export declare function readEslintVersionNextToObsidianmd(): string;
12
+ /**
13
+ * The mismatch warning for the installed packages. A probe that fails is reported as a warning too (it says what
14
+ * could not be read): the scan can still run, but the reader should know the check did not.
15
+ */
16
+ export declare function eslintMismatchWarning(running?: string, readNested?: () => string): string | undefined;
@@ -0,0 +1,45 @@
1
+ import { createRequire } from "node:module";
2
+ import { ESLint } from "eslint";
3
+ /** The major of a version such as `9.39.5` or `10.14.0`, or `undefined` for text that does not start with one. */
4
+ export function majorOf(version) {
5
+ const match = /^v?(\d+)\./.exec(version.trim());
6
+ return match?.[1] === undefined ? undefined : Number(match[1]);
7
+ }
8
+ /**
9
+ * The warning for an ESLint next to `eslint-plugin-obsidianmd` that is another major than the one that runs, or
10
+ * `undefined` when they agree. The preset takes ESLint's core rules (`builtinRules`) from the ESLint it resolves
11
+ * from its own location, so a nested ESLint 9 under a root ESLint 10 leaves `preserve-caught-error`,
12
+ * `no-useless-assignment` and `no-unassigned-vars` out of `recommended` without any error.
13
+ */
14
+ export function describeEslintMismatch(running, nested) {
15
+ const runningMajor = majorOf(running);
16
+ const nestedMajor = majorOf(nested);
17
+ if (runningMajor === undefined || nestedMajor === undefined || runningMajor === nestedMajor) {
18
+ return undefined;
19
+ }
20
+ return `eslint-plugin-obsidianmd reads ESLint's core rules from its own ESLint ${nested}, but ESLint ${running} runs. Rules that only ESLint ${String(Math.max(runningMajor, nestedMajor))} puts in "recommended" (preserve-caught-error, no-useless-assignment, no-unassigned-vars) may be missing from the scan. Add "overrides": { "eslint": "$eslint" } to package.json and run \`npm install\` (npm dedupe cannot move it: other obsidianmd dependencies peer on ESLint 9), or see docs/scanner.md ("ESLint 9 nested under eslint-plugin-obsidianmd").`;
21
+ }
22
+ /** The version of the `eslint` package that `eslint-plugin-obsidianmd` resolves, from the plugin's own location. */
23
+ export function readEslintVersionNextToObsidianmd() {
24
+ const fromKit = createRequire(import.meta.url);
25
+ const nextToPlugin = createRequire(fromKit.resolve("eslint-plugin-obsidianmd"));
26
+ const manifest = nextToPlugin("eslint/package.json");
27
+ if (typeof manifest === "object" && manifest !== null && "version" in manifest && typeof manifest.version === "string") {
28
+ return manifest.version;
29
+ }
30
+ throw new Error("the eslint package next to eslint-plugin-obsidianmd has no version in its package.json");
31
+ }
32
+ /**
33
+ * The mismatch warning for the installed packages. A probe that fails is reported as a warning too (it says what
34
+ * could not be read): the scan can still run, but the reader should know the check did not.
35
+ */
36
+ export function eslintMismatchWarning(running = ESLint.version, readNested = readEslintVersionNextToObsidianmd) {
37
+ let nested;
38
+ try {
39
+ nested = readNested();
40
+ }
41
+ catch (error) {
42
+ return `could not read the ESLint version next to eslint-plugin-obsidianmd, so a nested ESLint of another major would go unnoticed: ${error instanceof Error ? error.message : String(error)}`;
43
+ }
44
+ return describeEslintMismatch(running, nested);
45
+ }
@@ -0,0 +1,23 @@
1
+ /**
2
+ * The scan checks, in the order they run and print. The names are the reporter's step column, so they stay within
3
+ * its width.
4
+ */
5
+ export declare const SCAN_CHECKS: readonly ["lint", "css", "code", "meta"];
6
+ export type ScanCheck = (typeof SCAN_CHECKS)[number];
7
+ export interface Finding {
8
+ readonly check: ScanCheck;
9
+ /** Path relative to the plugin root, with `/` separators. */
10
+ readonly file: string;
11
+ /** 1-based; 0 when the finding has no position (a parse error from ESLint carries none). */
12
+ readonly line: number;
13
+ readonly rule: string;
14
+ readonly message: string;
15
+ /** Printed as a warning and does not fail the scan. */
16
+ readonly advisory?: boolean;
17
+ }
18
+ /** `file:line rule message`, the one layout every finding prints in. */
19
+ export declare function formatFinding(finding: Finding): string;
20
+ /** Stable order: by file, then line, then rule, so two runs print the same text. */
21
+ export declare function sortFindings(findings: readonly Finding[]): Finding[];
22
+ /** The findings of one check, sorted. */
23
+ export declare function findingsOf(findings: readonly Finding[], check: ScanCheck): Finding[];
@@ -0,0 +1,21 @@
1
+ /**
2
+ * The scan checks, in the order they run and print. The names are the reporter's step column, so they stay within
3
+ * its width.
4
+ */
5
+ export const SCAN_CHECKS = ["lint", "css", "code", "meta"];
6
+ /** `file:line rule message`, the one layout every finding prints in. */
7
+ export function formatFinding(finding) {
8
+ const position = finding.line > 0 ? `${finding.file}:${String(finding.line)}` : finding.file;
9
+ return `${position} ${finding.rule} ${finding.message}`;
10
+ }
11
+ /** Stable order: by file, then line, then rule, so two runs print the same text. */
12
+ export function sortFindings(findings) {
13
+ return [...findings].sort((a, b) => compare(a.file, b.file) || a.line - b.line || compare(a.rule, b.rule) || compare(a.message, b.message));
14
+ }
15
+ function compare(a, b) {
16
+ return a < b ? -1 : a > b ? 1 : 0;
17
+ }
18
+ /** The findings of one check, sorted. */
19
+ export function findingsOf(findings, check) {
20
+ return sortFindings(findings.filter((finding) => finding.check === check));
21
+ }
@@ -0,0 +1,16 @@
1
+ /** Splits `git ls-files -z` output into paths, dropping the empty entry after the last NUL. */
2
+ export declare function parseLsFiles(output: string): string[];
3
+ /**
4
+ * `env` without the `GIT_*` variables. A git hook or a worktree session exports `GIT_DIR`, `GIT_WORK_TREE` or
5
+ * `GIT_INDEX_FILE`, which would point `git ls-files` at another repository than the one in `cwd`.
6
+ */
7
+ export declare function gitFreeEnvironment(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
8
+ /**
9
+ * The files git tracks under `cwd`, as paths relative to it with `/` separators, minus entries that are not
10
+ * regular files on disk (deleted in the working tree but not yet committed, submodule folders, symlinks: the
11
+ * scanner reads the repository's files, and a link to a file outside the plugin folder is not one of them).
12
+ * Untracked build output (`main.js`, `coverage/`, `.preview/`) never reaches the scanner, so it is not here.
13
+ *
14
+ * Throws, saying what to do, when git is missing or `cwd` is not inside a repository.
15
+ */
16
+ export declare function listTrackedFiles(cwd: string): Promise<string[]>;