@templatical/quality 0.8.0 → 0.8.2

package/dist/index.d.ts

@@ -1,11 +1,16 @@
-import { Block } from '../../types/src/index.ts';
-import { SectionBlock } from '../../types/src/index.ts';
-import { TemplateContent } from '../../../types/src/index.ts';
-import { TemplateContent as TemplateContent_2 } from '../../types/src/index.ts';
-import { TemplateSettings } from '../../types/src/index.ts';
+import type { Block } from '@templatical/types';
+import type { SectionBlock } from '@templatical/types';
+import type { TemplateContent } from '@templatical/types';
+import type { TemplateSettings } from '@templatical/types';
 
 export declare const ACCESSIBILITY_RULES: Rule[];
 
+/** Options consumed only by the accessibility linter. */
+export declare interface AccessibilityLintOptions {
+    rules?: RuleOverrides;
+    thresholds?: Partial<LintThresholds>;
+}
+
 export declare interface AnchorInfo {
     href: string;
     text: string;
@@ -58,6 +63,7 @@ declare const en_2: {
     "a11y.link-vague-text": string;
     "a11y.link-href-empty": string;
     "a11y.link-target-blank-no-rel": string;
+    "a11y.link-nested-anchor": string;
     "a11y.text-all-caps": string;
     "a11y.text-low-contrast": string;
     "a11y.text-too-small": string;
@@ -99,6 +105,15 @@ declare const en_4: {
  * Extract every anchor from a TipTap-style HTML fragment. Used by
  * link-* rules. Doesn't try to be a full DOM — only the data the rules
  * need.
+ *
+ * Nested `<a>` is invalid HTML; htmlparser2 follows the HTML5 spec and
+ * emits an implicit `</a>` when a second `<a>` opens, so anchors are
+ * effectively flat siblings. We mirror that with a single in-flight
+ * anchor (no stack); a defensive finalize-on-reopen handles the
+ * theoretical case where the parser ever stops emitting the implicit
+ * close. Detecting nested-anchor markup as its own concern lives in
+ * the `a11y.link-nested-anchor` rule, which inspects the raw input
+ * before this normalization.
  */
 export declare function extractAnchors(html: string): AnchorInfo[];
 
@@ -148,6 +163,30 @@ export declare function getMessages(locale: string): MessageMap;
 
 export declare function getStructureMessages(locale: string): StructureMessageMap;
 
+/**
+ * Whether the raw HTML contains an `<a>` opened inside another open
+ * `<a>` — invalid markup that htmlparser2 silently normalizes by
+ * emitting an implicit `</a>` before the inner open. `extractAnchors`
+ * runs against the normalized parse and therefore can't distinguish
+ * nested-from-sibling input; this helper inspects the raw text so the
+ * `a11y.link-nested-anchor` rule can flag the structural problem.
+ *
+ * Tokenization here ignores anchor-like tokens inside HTML comments,
+ * which is enough for TipTap email-template HTML. CDATA, `<script>`,
+ * and attribute-value occurrences aren't expected in this surface.
+ */
+export declare function hasNestedAnchors(html: string): boolean;
+
+/**
+ * `true` when no linter would run for the given options — either the
+ * global `disabled` flag is set, or every per-tool key is `false`.
+ *
+ * The editor uses this to skip lazy-loading `@templatical/quality`, hide
+ * the Issues sidebar tab, and suppress inline canvas badges. Headless
+ * callers can use it to short-circuit before any linter call.
+ */
+export declare function isLintFullyDisabled(options: LintOptions | undefined): boolean;
+
 export declare function isOpaqueHex(input: string | undefined | null): boolean;
 
 export declare const LINK_RULES: Rule[];
@@ -156,6 +195,21 @@ export declare type LinkMessageMap = typeof en_4;
 
 export declare type LinkRuleMessageId = keyof LinkMessageMap;
 
+/** Options consumed only by the links linter. */
+export declare interface LinksLintOptions {
+    rules?: RuleOverrides;
+    /**
+     * Host patterns that should flag as "staging / non-production".
+     * Each entry is a glob-style pattern matched against the URL host.
+     * `*` matches any run of characters (including `.`), so `*.staging.*`
+     * matches `app.staging.example.com`.
+     *
+     * Default: ['localhost', '127.0.0.1', '0.0.0.0', '*.local',
+     *           '*.staging.*', '*.dev.*']
+     */
+    nonProductionHosts?: string[];
+}
+
 export declare function lintAccessibility(content: TemplateContent, options?: LintOptions): LintIssue[];
 
 export declare interface LintIssue {
@@ -169,19 +223,6 @@ export declare interface LintIssue {
 
 export declare function lintLinks(content: TemplateContent, options?: LintOptions): LintIssue[];
 
-export declare interface LintLinksOptions {
-    /**
-     * Host patterns that should flag as "staging / non-production".
-     * Each entry is a glob-style pattern matched against the URL host.
-     * `*` matches any run of characters (including `.`), so `*.staging.*`
-     * matches `app.staging.example.com`.
-     *
-     * Default: ['localhost', '127.0.0.1', '0.0.0.0', '*.local',
-     *           '*.staging.*', '*.dev.*']
-     */
-    nonProductionHosts?: string[];
-}
-
 export declare interface LintOptions {
     /**
      * Fully disable linting. When true, the editor skips lazy-loading the
@@ -190,11 +231,21 @@ export declare interface LintOptions {
     disabled?: boolean;
     /** Locale for vague-text dictionaries and message text. Falls back to `en`. */
     locale?: string;
-    /** Per-rule severity override. Set to `'off'` to disable a specific rule. */
-    rules?: Record<string, Severity>;
-    thresholds?: Partial<LintThresholds>;
-    /** Per-linter knobs. Only `lintLinks` reads `links` today. */
-    links?: LintLinksOptions;
+    /**
+     * Accessibility linter config. Set to `false` to disable the whole
+     * `lintAccessibility` linter without enumerating its rules.
+     */
+    accessibility?: false | AccessibilityLintOptions;
+    /**
+     * Structure linter config. Set to `false` to disable the whole
+     * `lintStructure` linter without enumerating its rules.
+     */
+    structure?: false | StructureLintOptions;
+    /**
+     * Links linter config. Set to `false` to disable the whole `lintLinks`
+     * linter without enumerating its rules.
+     */
+    links?: false | LinksLintOptions;
 }
 
 export declare interface LintPatch {
@@ -227,7 +278,7 @@ export declare interface ResolvedLinksOptions {
 
 export declare interface ResolvedOptions {
     locale: string;
-    rules: Record<string, Severity>;
+    rules: RuleOverrides;
     thresholds: LintThresholds;
     links: ResolvedLinksOptions;
     /** Returns the effective severity for a rule (override or default). */
@@ -245,7 +296,7 @@ export declare interface Rule {
     /** Block-level rule. Returns a hit or null. */
     block?: (block: Block, ctx: WalkContext, opts: ResolvedOptions) => RuleHit | null;
     /** Template-level rule. Runs once after the walk. */
-    template?: (content: TemplateContent_2, opts: ResolvedOptions) => RuleHit[];
+    template?: (content: TemplateContent, opts: ResolvedOptions) => RuleHit[];
 }
 
 /**
@@ -269,10 +320,22 @@ export declare interface RuleMeta {
     severity: Exclude<Severity, "off">;
 }
 
+/**
+ * Per-rule severity override. Set a rule to `'off'` to disable it.
+ * Keys are the full prefixed rule IDs (`a11y.*`, `structure.*`, `link.*`)
+ * so a value copied from `LintIssue.ruleId` pastes straight in.
+ */
+export declare type RuleOverrides = Record<string, Severity>;
+
 export declare type Severity = "error" | "warning" | "info" | "off";
 
 export declare const STRUCTURE_RULES: Rule[];
 
+/** Options consumed only by the structure linter. */
+export declare interface StructureLintOptions {
+    rules?: RuleOverrides;
+}
+
 export declare type StructureMessageMap = typeof en_3;
 
 export declare type StructureRuleMessageId = keyof StructureMessageMap;
@@ -306,7 +369,7 @@ export declare type Visitor = (block: Block, ctx: WalkContext) => void;
  * descend into a section that lives inside a column. Custom blocks are
  * visited but not descended into.
  */
-export declare function walkBlocks(content: TemplateContent_2, visit: Visitor): void;
+export declare function walkBlocks(content: TemplateContent, visit: Visitor): void;
 
 export declare interface WalkContext {
     parent: Block | null;
@@ -334,6 +397,6 @@ export declare interface WalkContext {
  *
  * Each rule iterates this list once and decides per occurrence.
  */
-export declare function walkUrls(content: TemplateContent_2): UrlOccurrence[];
+export declare function walkUrls(content: TemplateContent): UrlOccurrence[];
 
 export { }