This document defines approved patterns for audit-sensitive changes. Use it with CONTRIBUTING.md and docs/development/plugin-scorecard.md.
These rules apply to production code by default and to tests where noted.
- Do not inject untrusted content with direct
innerHTMLassignment in production rendering paths. - Use approved sanitizing and append utilities already used in the codebase (for example,
sanitizeAndAppendHtml(...)).
This blocks the audit class for unsafe HTML injection and aligns with SDL scanner expectations.
// Bad
container.innerHTML = html;
// Good
sanitizeAndAppendHtml(container, html);- Avoid
eslint-disableunless there is no viable typed or structural alternative. - Every disable must include a short inline reason.
// Bad
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// Good
// eslint-disable-next-line @typescript-eslint/no-explicit-any -- Obsidian internal API is untyped here; narrowed immediately below.- Do not propagate
as anyacross a file. - Prefer one boundary cast at input edges, then use typed interfaces throughout the rest of the flow.
// Better boundary cast pattern
const pluginApi = plugin as unknown as PluginTestFixture;- In production UI paths, prefer
activeDocumentover globaldocumentwhere popout compatibility rules apply. - Prefer
window.setTimeout(...),window.clearTimeout(...), and otherwindow.*timer APIs overactiveWindow.*or bare timer calls. - Use
window.crypto(or Obsidian-provided APIs) instead ofglobalThisfor browser globals.
// Prefer in popout-aware UI code
const el = activeDocument.createElement("div");
const handle = window.setTimeout(() => {
// ...
}, 100);
window.clearTimeout(handle);
view.registerDomEvent(activeDocument, "keydown", handler);- Keep source CSS free of
!importantdeclarations. - Build sufficient specificity from an existing plugin root, component, and state or element selector.
- Check cascade order and component ownership before increasing specificity.
- Do not use IDs, duplicated classes, or unscoped
bodyselectors as specificity shortcuts.
.rss-dashboard-container .rss-feed-card.is-selected > .rss-card-action {
color: var(--text-accent);
}If a host rule cannot be overridden cleanly, move the style to a plugin-owned wrapper or property instead of creating an exception.
- In production code, prefer Obsidian DOM helpers:
createDiv()instead ofdocument.createElement("div")createEl("input"),createEl("button"), etc.createSpan()andcreateFragment()where applicable
- Keep exceptions localized and documented when test polyfills require plain DOM calls.
- Follow current lint restrictions on module imports and approved alternatives.
- If a restricted import is encountered, use the codebase-approved source (for example, Obsidian-provided APIs).
Before opening a PR:
npm run lintpasses for changed files.npm run test:unitor targeted tests pass.- No new undocumented lint suppressions.
- No new unsafe HTML injection in production paths.
- New UI changes follow popout-safe and DOM-helper conventions.
npm run check:importantpasses for CSS or CSS-policy changes.
CONTRIBUTING.md(Compliance Declarations)docs/development/plugin-scorecard.md(live backlog and priorities)docs/SECURITY.md(stakeholder-facing security disclosures)