npm - @svelte-vitals/core - Versions diffs - 0.42.0 → 0.43.0 - Mend

@svelte-vitals/core 0.42.0 → 0.43.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md CHANGED Viewed

@@ -3,7 +3,7 @@
 [![npm](https://img.shields.io/npm/v/@svelte-vitals/core)](https://www.npmjs.com/package/@svelte-vitals/core)
 [![MIT](https://img.shields.io/npm/l/@svelte-vitals/core)](https://opensource.org/licenses/MIT)
-Runtime-agnostic core for [svelte-vitals](https://github.com/oekazuma/svelte-vitals): shared types, the rule engine, scorer, and reporters, plus the full rule set across five categories — SEO, Performance, Correctness, Security, Architecture.
+Runtime-agnostic core for [svelte-vitals](https://github.com/oekazuma/svelte-vitals): shared types, the rule engine, scorer, and reporters, plus the full rule set across six categories — SEO, Performance, Correctness, Security, Architecture, Accessibility.
 This package is **mode-independent** and contains no I/O — it operates on a normalized `ResolvedHead[]` intermediate representation, so the same rules run unchanged whether heads come from static source analysis (the `svelte-vitals` CLI) or from prerendered HTML (the `@svelte-vitals/vite` plugin). It has zero runtime dependencies and no `node:` imports.

package/dist/index.d.ts CHANGED Viewed

@@ -81,6 +81,18 @@ interface Project {
      * list is never empty: `$lib` is always prepended.
      */
     kitAliases?: KitAlias[];
+    /**
+     * Whether `src/app.html` opens with `<!doctype html>` (a11y/doctype). Set from the same read
+     * as `htmlLang`; absent when the file wasn't read (missing or unreadable) — the rule stays
+     * silent then, like `viteMinifyDisabled`'s absent convention.
+     */
+    appHtmlDoctype?: boolean;
+    /**
+     * Literal `id` attributes in `src/app.html`, from the same read as `htmlLang`. The shell is part
+     * of every rendered document, so its ids satisfy a route's id references (a11y/no-missing-id-ref);
+     * absent when the file wasn't read.
+     */
+    appHtmlIds?: string[];
 }
 declare const defaultProject: Project;
 /** A concrete, agent-actionable remediation for a finding (design §10, issue #18). */
@@ -113,7 +125,7 @@ interface Result {
     line?: number;
 }
 type Scope = 'route' | 'project' | 'component';
-type Category = 'seo' | 'performance' | 'correctness' | 'security' | 'architecture';
+type Category = 'seo' | 'performance' | 'correctness' | 'security' | 'architecture' | 'a11y';
 /**
  * Every category, as a runtime list — for validating a user-supplied category
  * name and naming the known ones in the error. One definition so a category
@@ -318,6 +330,81 @@ interface ResolvedHeadings {
     componentHeadings?: HeadingInfo[];
 }
+/** One step of a template branch address: which exclusive block, and which arm of it. */
+interface BranchStep {
+    /** index of the {#if}/{#await} block among its file's blocks (document order) */
+    group: number;
+    /** branch index within the group (if: 0..n consequent→else; await: 0=pending,1=then,2=catch) */
+    branch: number;
+}
+/** Where a folded occurrence sits, for the finding location. */
+interface A11yOccurrenceInfo {
+    file: string;
+    line: number;
+}
+/**
+ * Route-scoped a11y facts, the mode-independent boundary for the landmark/id rules
+ * (mirrors headings.ts). Source mode composes the layout chain plus its resolved
+ * components; rendered mode reads the prerendered document.
+ */
+interface ResolvedA11y {
+    route: string;
+    /** representatives per landmark kind after the branch-aware fold ('main' | 'banner' | 'contentinfo' | 'complementary') */
+    landmarks: Record<string, A11yOccurrenceInfo[]>;
+    /** landmark occurrences nested inside another landmark after composition */
+    nestedLandmarks: {
+        kind: string;
+        within: string;
+        file: string;
+        line: number;
+    }[];
+    /** representatives per literal id */
+    ids: Record<string, A11yOccurrenceInfo[]>;
+    /** literal id references */
+    idRefs: {
+        id: string;
+        attr: string;
+        file: string;
+        line: number;
+    }[];
+    /** optimistic candidates: every literal id anywhere (all branches, each/snippet bodies, components, app.html) */
+    idCandidates: string[];
+    /** closed world holds: every component resolved, no depth truncation, no {@html}/spread, no dynamic id */
+    fullyResolved: boolean;
+}
+type Foldable = {
+    key: string;
+    path: BranchStep[];
+    repeatable: boolean;
+};
+/**
+ * Branch-aware occurrence fold (design "Control-flow semantics"): within a branch
+ * occurrences sum, across the arms of one exclusive block the arm with the most
+ * occurrences wins (tie → lowest branch index) and ITS occurrences are the group's
+ * representatives — so a caller's count is always `list.length`, with a location per
+ * representative. `{#each}`/`{#snippet}` occurrences render 0..N times and drop out.
+ * The max is per key: there is no scalar total to maximize.
+ */
+declare function foldOccurrences<T extends Foldable>(nodes: T[]): Map<string, T[]>;
+/**
+ * Decode a fragment identifier the way navigation does before matching an element id
+ * (`href="#caf%C3%A9"` targets `id="café"`). Malformed escapes are kept verbatim —
+ * the browser would also fail to decode them, so the raw text is the comparable form.
+ */
+declare function decodeFragmentId(fragment: string): string;
+/** Whitespace-split tokens of a (possibly undefined) literal attribute value. */
+declare function splitTokens(value: string | undefined): string[];
+/** Explicit `role` values that map to the landmark kinds the route rules inspect. */
+declare const LANDMARK_ROLES: ReadonlySet<string>;
+/** Attributes whose (whitespace-tokenized) values reference element ids. */
+declare const IDREF_ATTRS: readonly string[];
+/**
+ * Whether a decoded URL fragment is HTML's "top of the document" indicator: `#top` (ASCII
+ * case-insensitive) scrolls to the top when no element has that id, so it is never a missing
+ * reference. Compare AFTER percent-decoding — `#%74op` navigates identically to `#top`.
+ */
+declare function isTopFragment(id: string): boolean;
 /**
  * Component-body facts for the Correctness category — the source-analysis boundary
  * (mirrors images.ts / headings.ts). Collected by the static (CLI) provider only;
@@ -402,6 +489,43 @@ interface BasePathLinkFact {
     /** 1-based source line, or 0 if unknown. */
     line: number;
 }
+/** An interactive element (e.g. `<button>`) found nested inside another interactive
+ *  container (e.g. `<a href>`) (a11y/interactive-nesting). */
+interface InteractiveNestingFact {
+    containerTag: string;
+    descendantTag: string;
+    /** 1-based source line of the descendant, or 0 if unknown. */
+    line: number;
+}
+/** A `button`/`a href`/`input type="image"` with no computable accessible name (a11y/accessible-name). */
+interface UnnamedInteractiveFact {
+    tag: string;
+    /** 1-based source line, or 0 if unknown. */
+    line: number;
+}
+/** An element carrying a `role` and/or `aria-*` attribute(s) (a11y ARIA rules). */
+interface AriaElementFact {
+    tag: string;
+    /** 1-based source line, or 0 if unknown. */
+    line: number;
+    /** literal role value; undefined = no role attr; { expression: true } = dynamic */
+    role?: {
+        literal?: string;
+        expression?: boolean;
+    };
+    /** every aria-* attribute on the element */
+    aria: {
+        name: string;
+        literal?: string;
+        expression?: boolean;
+        line: number;
+    }[];
+    /** literal `type` of an `<input>`, lowercased; undefined for non-inputs or a dynamic type */
+    inputType?: string;
+    /** Set when the element also carries a spread attribute — its full attribute set is
+     *  unknowable, so required-prop presence checks must treat it as satisfied (a11y/required-aria-props). */
+    hasSpread?: true;
+}
 /** Reactivity/correctness + security + architecture facts parsed from one `.svelte` component. */
 interface ComponentFacts {
     /** Source file the component came from. */
@@ -486,6 +610,31 @@ interface ComponentFacts {
         url: string;
         line: number;
     }[];
+    /** Elements carrying a role or any aria-* attribute (a11y ARIA rules). */
+    ariaElements?: AriaElementFact[];
+    /** Interactive elements nested inside another interactive container (a11y/interactive-nesting). */
+    interactiveNestings?: InteractiveNestingFact[];
+    /** `button`/`a href`/`input type="image"` elements with no computable accessible name (a11y/accessible-name). */
+    unnamedInteractive?: UnnamedInteractiveFact[];
+    /** `<label>` elements with neither a `for` attribute nor a wrapped labelable descendant (a11y/label-has-control). */
+    unassociatedLabels?: {
+        line: number;
+    }[];
+    /** Text nodes whose trimmed content opens with a bullet character followed by whitespace, outside any `li` (a11y/use-list). */
+    bulletTexts?: {
+        line: number;
+        char: string;
+    }[];
+    /** `<select required>` (no `multiple`, display size absent or ≤ 1) whose first `option` element
+     *  child is not a placeholder label option (a11y/placeholder-label-option). */
+    selectsMissingPlaceholder?: {
+        line: number;
+    }[];
+    /** `<time>` with no `datetime` attribute whose literal text content is not machine-readable (a11y/require-datetime). */
+    timesMissingDatetime?: {
+        line: number;
+        text: string;
+    }[];
     /** Set when the file failed to read or parse and these facts are the empty fallback — the file was NOT analyzed. */
     parseFailed?: true;
 }
@@ -510,10 +659,10 @@ declare function parseComponentFacts(source: string, filename: string): ParsedFa
 declare function emptyComponentFacts(file: string): ComponentFacts;
 /**
  * Scan every `.svelte` component and `.svelte.ts`/`.svelte.js` runes module under `src/`
- * for Correctness/Security/Architecture/Bundle-Performance facts. Independent of route
- * resolution — covers `$lib` and non-route components too. A file that fails to read or
- * parse contributes empty facts instead of aborting the whole scan (dev tooling must
- * never throw).
+ * for Correctness/Security/Architecture/Bundle-Performance/Accessibility facts. Independent
+ * of route resolution — covers `$lib` and non-route components too. A file that fails to
+ * read or parse contributes empty facts instead of aborting the whole scan (dev tooling
+ * must never throw).
  */
 declare function collectComponentFacts(rt: Runtime, cwd: string): Promise<ComponentFacts[]>;
@@ -984,6 +1133,8 @@ interface RuleContext {
     images?: ResolvedImages[];
     /** Per-route page-body headings for seo/single-h1 (absent in modes that don't collect them). */
     headings?: ResolvedHeadings[];
+    /** Per-route composed landmark/id occurrences for the route-scoped a11y rules (absent in modes that don't collect them). */
+    a11y?: ResolvedA11y[];
     /** Per-file component-body facts for Correctness rules (static/CLI mode only). */
     components?: ComponentFacts[];
     /** Per-file SvelteKit route/hooks facts for the SSR shared-state rules (static/CLI + vite build mode only). */
@@ -1400,6 +1551,57 @@ declare const performanceSequentialAwaits: Rule;
  */
 declare const performanceStateRaw: Rule;
+declare const a11yInvalidRole: Rule;
+declare const a11yUnknownAriaAttribute: Rule;
+declare const a11yRequiredAriaProps: Rule;
+declare const a11yInvalidAriaValue: Rule;
+declare const a11yInteractiveNesting: Rule;
+declare const a11yAccessibleName: Rule;
+declare const a11yLabelHasControl: Rule;
+declare const a11yUseList: Rule;
+declare const a11yPlaceholderLabelOption: Rule;
+declare const a11yRequireDatetime: Rule;
+declare const a11yDoctype: Rule;
+/**
+ * a11y/duplicate-landmark — a composed route (layout chain + page) yields more than one
+ * `main` / `banner` / `contentinfo` landmark. `ctx.a11y[].landmarks` already holds the
+ * branch-aware-folded representatives, so this rule only counts them per kind, in the
+ * fixed KINDS order (it decides emission order and the PASS anchor).
+ */
+declare const a11yDuplicateLandmark: Rule;
+/**
+ * a11y/top-level-landmark — a landmark (`main`/`banner`/`complementary`/`contentinfo`) that
+ * composition places inside another landmark. `ctx.a11y[].nestedLandmarks` already carries one
+ * entry per nested occurrence, so this rule only reports them.
+ */
+declare const a11yTopLevelLandmark: Rule;
+/**
+ * a11y/id-duplication — a literal id repeated within a composed route. `ctx.a11y[].ids`
+ * already holds the branch-aware-folded representatives per id, so this rule only counts them.
+ */
+declare const a11yIdDuplication: Rule;
+/**
+ * a11y/no-missing-id-ref — a `for`/`aria-labelledby`/`aria-describedby`/`aria-controls`/
+ * `aria-activedescendant`/same-page `href="#…"` referencing an `id` absent from the composed
+ * route. Universal ("no element anywhere defines this id") needs a closed world, so this rule
+ * runs only on routes `ctx.a11y[].fullyResolved` marks fully resolved — see the rule docs.
+ */
+declare const a11yNoMissingIdRef: Rule;
 declare const allRules: Rule[];
 /** One configurable option of a rule, flattened for `svelte-vitals explain`'s output. */
@@ -1748,4 +1950,4 @@ declare function formatHtmlReport(results: Result[], config: Config, meta: {
     coreVersion?: string;
 }): string;
-export { APP_SCRIPT, APP_STYLE, type AppSnapshot, BAND_COLOR, CATEGORIES, CHILD_NODE_KEYS, type Category, type Classification, type CompiledOverride, type ComponentFacts, type Config, type ConsoleReportOptions, type Detection, type EachBlockFact, type EffectFact, type FailedRule, type Fix, type HeadProvider, type HeadTag, type HeadingInfo, type HealthResult, type ImageInfo, type JsonReport, type KitAlias, type KitModuleFacts, type OrphanEffectFact, type Palette, type Presence, type Project, ROBOTS_SOURCE_PATHS, type RawKitAliases, type ResolvedHead, type ResolvedHeadings, type ResolvedImages, type Result, type RouteBadge, type Rule, type RuleContext, type RuleEvidence, type RuleInfo, type RuleOptionInfo, type RuleOptionSpec, type RuleOptions, type RuleOptionsSpec, type RuleOverride, type RuleSetting, type RuleSettingObject, type Runtime, SITEMAP_SOURCE_PATHS, SVELTE_CONFIG_FILES, type Scope, type ScoreModel, type ScoreOptions, type ScoreResult, type Severity, type SourceSpan, type Summary, type SuppressionDirective, type TreatDynamicAs, VITE_CONFIG_FILES, type Value, type ViteKitConfigResult, allRules, applyOverrides, applyRuleSeverities, architectureComponentSize, architectureDirectoryNaming, architectureDocLinkTarget, architecturePrivateScopeImport, architecturePropCount, architectureReservedDirectoryNames, architectureReservedNamePlacement, architectureRouteComponentImport, architectureUnitEntryFile, attrText, attrTextOf, attrValue, attrValueOf, buildHtmlDocument, buildJsonReport, classify, collectComponentFacts, collectKitModuleFacts, collectSourceFiles, compileOverrides, computeHealth, computeScore, correctnessBasePathNavigation, correctnessCheckableBindValue, correctnessEachIndexKey, correctnessEachKey, correctnessEffectAsDerived, correctnessEffectAsOnMount, correctnessInstanceBrowserGlobal, correctnessNonreactiveBuiltinState, correctnessOrphanEffect, correctnessOrphanLifecycle, correctnessPropMutation, correctnessServerBrowserGlobal, correctnessStalePropDerivation, correctnessUnmutatedState, defaultConfig, defaultProject, defineConfig, docsUrlFor, effectiveSeverity, emptyComponentFacts, emptyKitModuleFacts, escapeHtml, explainRule, findAttr, findKitAliasesInSvelteConfig, findKitPathsBaseInSvelteConfig, findKitPathsBaseInViteConfig, findMinifyDisabled, formatAgentReport, formatConsoleReport, formatFailedRuleWarning, formatGithubReport, formatHtmlReport, formatJsonReport, formatMarkdownReport, formatSarifReport, hasFailureAtOrAbove, headTagRule, imageRule, intOption, isMentionedAnywhere, isPenalized, lineOf, linkRule, listOption, mapOption, noColorPalette, overrideMatches, parseComponentFacts, parseKitModuleFacts, performanceFontPreloadCrossorigin, performanceHeavyImport, performanceImageDimensions, performanceImageLoadingHint, performanceLcpImage, performanceLoadWaterfall, performanceMinifyDisabled, performanceNamespaceImport, performancePreconnect, performancePreloadMissingAs, performanceRenderBlockingScript, performanceResponsiveImage, performanceSequentialAwaits, performanceStateRaw, renderAppShell, resolveKitAliases, resolveKitPathsBase, resolveRepoLocalPath, resolveRuleOptions, resolveRunesModuleSpecifier, runRules, safeHref, scoreBand, scoreColor, scoresByCategory, securityHandlerStateWrite, securityJavascriptUrl, securityRawHtml, securityServerModuleState, securitySharedStateImport, selectRules, seoCanonicalUrl, seoCharset, seoDescriptionLength, seoDescriptionPresence, seoDuplicateDescription, seoDuplicateTitle, seoHeadingLevelSkip, seoHreflang, seoHtmlLang, seoImageAlt, seoIndexability, seoJsonLd, seoJsonLdDateFormat, seoJsonLdDeprecatedType, seoJsonLdPlaceholder, seoJsonLdRelativeUrl, seoJsonLdRequiredProps, seoJsonLdValidity, seoOgDescription, seoOgImage, seoOgTitle, seoOgUrl, seoRobotsTxt, seoSingleH1, seoSitemapInRobots, seoSitemapXml, seoSsrDisabled, seoTitleLength, seoTitlePresence, seoTwitterCard, seoViewport, settingOptions, settingSeverity, shouldSkipRangeCheck, summarize, terminalSafe, textFromNodes, validateRuleOptions, validateRuleSetting, valueFromNodes, withFailedRulesOff };
+export { type A11yOccurrenceInfo, APP_SCRIPT, APP_STYLE, type AppSnapshot, BAND_COLOR, type BranchStep, CATEGORIES, CHILD_NODE_KEYS, type Category, type Classification, type CompiledOverride, type ComponentFacts, type Config, type ConsoleReportOptions, type Detection, type EachBlockFact, type EffectFact, type FailedRule, type Fix, type HeadProvider, type HeadTag, type HeadingInfo, type HealthResult, IDREF_ATTRS, type ImageInfo, type JsonReport, type KitAlias, type KitModuleFacts, LANDMARK_ROLES, type OrphanEffectFact, type Palette, type Presence, type Project, ROBOTS_SOURCE_PATHS, type RawKitAliases, type ResolvedA11y, type ResolvedHead, type ResolvedHeadings, type ResolvedImages, type Result, type RouteBadge, type Rule, type RuleContext, type RuleEvidence, type RuleInfo, type RuleOptionInfo, type RuleOptionSpec, type RuleOptions, type RuleOptionsSpec, type RuleOverride, type RuleSetting, type RuleSettingObject, type Runtime, SITEMAP_SOURCE_PATHS, SVELTE_CONFIG_FILES, type Scope, type ScoreModel, type ScoreOptions, type ScoreResult, type Severity, type SourceSpan, type Summary, type SuppressionDirective, type TreatDynamicAs, VITE_CONFIG_FILES, type Value, type ViteKitConfigResult, a11yAccessibleName, a11yDoctype, a11yDuplicateLandmark, a11yIdDuplication, a11yInteractiveNesting, a11yInvalidAriaValue, a11yInvalidRole, a11yLabelHasControl, a11yNoMissingIdRef, a11yPlaceholderLabelOption, a11yRequireDatetime, a11yRequiredAriaProps, a11yTopLevelLandmark, a11yUnknownAriaAttribute, a11yUseList, allRules, applyOverrides, applyRuleSeverities, architectureComponentSize, architectureDirectoryNaming, architectureDocLinkTarget, architecturePrivateScopeImport, architecturePropCount, architectureReservedDirectoryNames, architectureReservedNamePlacement, architectureRouteComponentImport, architectureUnitEntryFile, attrText, attrTextOf, attrValue, attrValueOf, buildHtmlDocument, buildJsonReport, classify, collectComponentFacts, collectKitModuleFacts, collectSourceFiles, compileOverrides, computeHealth, computeScore, correctnessBasePathNavigation, correctnessCheckableBindValue, correctnessEachIndexKey, correctnessEachKey, correctnessEffectAsDerived, correctnessEffectAsOnMount, correctnessInstanceBrowserGlobal, correctnessNonreactiveBuiltinState, correctnessOrphanEffect, correctnessOrphanLifecycle, correctnessPropMutation, correctnessServerBrowserGlobal, correctnessStalePropDerivation, correctnessUnmutatedState, decodeFragmentId, defaultConfig, defaultProject, defineConfig, docsUrlFor, effectiveSeverity, emptyComponentFacts, emptyKitModuleFacts, escapeHtml, explainRule, findAttr, findKitAliasesInSvelteConfig, findKitPathsBaseInSvelteConfig, findKitPathsBaseInViteConfig, findMinifyDisabled, foldOccurrences, formatAgentReport, formatConsoleReport, formatFailedRuleWarning, formatGithubReport, formatHtmlReport, formatJsonReport, formatMarkdownReport, formatSarifReport, hasFailureAtOrAbove, headTagRule, imageRule, intOption, isMentionedAnywhere, isPenalized, isTopFragment, lineOf, linkRule, listOption, mapOption, noColorPalette, overrideMatches, parseComponentFacts, parseKitModuleFacts, performanceFontPreloadCrossorigin, performanceHeavyImport, performanceImageDimensions, performanceImageLoadingHint, performanceLcpImage, performanceLoadWaterfall, performanceMinifyDisabled, performanceNamespaceImport, performancePreconnect, performancePreloadMissingAs, performanceRenderBlockingScript, performanceResponsiveImage, performanceSequentialAwaits, performanceStateRaw, renderAppShell, resolveKitAliases, resolveKitPathsBase, resolveRepoLocalPath, resolveRuleOptions, resolveRunesModuleSpecifier, runRules, safeHref, scoreBand, scoreColor, scoresByCategory, securityHandlerStateWrite, securityJavascriptUrl, securityRawHtml, securityServerModuleState, securitySharedStateImport, selectRules, seoCanonicalUrl, seoCharset, seoDescriptionLength, seoDescriptionPresence, seoDuplicateDescription, seoDuplicateTitle, seoHeadingLevelSkip, seoHreflang, seoHtmlLang, seoImageAlt, seoIndexability, seoJsonLd, seoJsonLdDateFormat, seoJsonLdDeprecatedType, seoJsonLdPlaceholder, seoJsonLdRelativeUrl, seoJsonLdRequiredProps, seoJsonLdValidity, seoOgDescription, seoOgImage, seoOgTitle, seoOgUrl, seoRobotsTxt, seoSingleH1, seoSitemapInRobots, seoSitemapXml, seoSsrDisabled, seoTitleLength, seoTitlePresence, seoTwitterCard, seoViewport, settingOptions, settingSeverity, shouldSkipRangeCheck, splitTokens, summarize, terminalSafe, textFromNodes, validateRuleOptions, validateRuleSetting, valueFromNodes, withFailedRulesOff };