@templatical/quality 0.7.3 → 0.8.1

package/dist/index.d.ts

@@ -4,43 +4,12 @@ import { TemplateContent } from '../../../types/src/index.ts';
 import { TemplateContent as TemplateContent_2 } from '../../types/src/index.ts';
 import { TemplateSettings } from '../../types/src/index.ts';
 
-export declare interface A11yIssue {
-    /** Block id, or null for template-level issues. */
-    blockId: string | null;
-    ruleId: string;
-    severity: Exclude<Severity, "off">;
-    message: string;
-    fix?: A11yPatch;
-}
-
-export declare interface A11yOptions {
-    /**
-     * Fully disable linting. When true, the editor skips lazy-loading the
-     * package, hides the sidebar tab, and suppresses inline badges.
-     */
-    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<A11yThresholds>;
-}
-
-export declare interface A11yPatch {
-    description: string;
-    apply: (ctx: A11yPatchContext) => void;
-}
-
-export declare interface A11yPatchContext {
-    updateBlock: (blockId: string, patch: Partial<Block>) => void;
-    updateSettings: (patch: Partial<TemplateSettings>) => void;
-}
+export declare const ACCESSIBILITY_RULES: Rule[];
 
-export declare interface A11yThresholds {
-    altMaxLength: number;
-    minFontSize: number;
-    allCapsMinLength: number;
-    minTouchTargetPx: number;
+/** Options consumed only by the accessibility linter. */
+export declare interface AccessibilityLintOptions {
+    rules?: RuleOverrides;
+    thresholds?: Partial<LintThresholds>;
 }
 
 export declare interface AnchorInfo {
@@ -52,7 +21,9 @@ export declare interface AnchorInfo {
     hasImageWithAlt: boolean;
 }
 
-export declare const DEFAULT_THRESHOLDS: A11yThresholds;
+export declare const DEFAULT_A11Y_THRESHOLDS: LintThresholds;
+
+export declare const DEFAULT_NON_PRODUCTION_HOSTS: string[];
 
 export declare type Dictionary = typeof en;
 
@@ -81,25 +52,53 @@ declare const en: {
  * Templates use `{name}` placeholders, interpolated by `formatMessage`.
  */
 declare const en_2: {
-    "img-missing-alt": string;
-    "img-alt-is-filename": string;
-    "img-alt-too-long": string;
-    "img-decorative-needs-empty-alt": string;
-    "img-linked-no-context": string;
-    "heading-empty": string;
-    "heading-skip-level": string;
-    "heading-multiple-h1": string;
-    "link-empty": string;
-    "link-vague-text": string;
-    "link-href-empty": string;
-    "link-target-blank-no-rel": string;
-    "text-all-caps": string;
-    "text-low-contrast": string;
-    "text-too-small": string;
-    "button-vague-label": string;
-    "button-touch-target": string;
-    "button-low-contrast": string;
-    "missing-preheader": string;
+    "a11y.img-missing-alt": string;
+    "a11y.img-alt-is-filename": string;
+    "a11y.img-alt-too-long": string;
+    "a11y.img-decorative-needs-empty-alt": string;
+    "a11y.img-linked-no-context": string;
+    "a11y.heading-empty": string;
+    "a11y.heading-skip-level": string;
+    "a11y.heading-multiple-h1": string;
+    "a11y.link-empty": string;
+    "a11y.link-vague-text": string;
+    "a11y.link-href-empty": string;
+    "a11y.link-target-blank-no-rel": string;
+    "a11y.text-all-caps": string;
+    "a11y.text-low-contrast": string;
+    "a11y.text-too-small": string;
+    "a11y.button-vague-label": string;
+    "a11y.button-touch-target": string;
+    "a11y.button-low-contrast": string;
+    "a11y.missing-preheader": string;
+};
+
+/**
+ * English structure-rule messages. The source of truth — other locales
+ * annotate themselves `typeof en` so missing or extra keys fail typecheck.
+ *
+ * Templates use `{name}` placeholders, interpolated by `formatMessage`.
+ */
+declare const en_3: {
+    "structure.duplicate-block-id": string;
+    "structure.section-column-mismatch": string;
+    "structure.nested-section": string;
+    "structure.empty-section": string;
+    "structure.empty-column": string;
+};
+
+/**
+ * English link-rule messages. The source of truth — other locales annotate
+ * themselves `typeof en` so missing or extra keys fail typecheck.
+ *
+ * Templates use `{name}` placeholders, interpolated by `formatLinkMessage`.
+ */
+declare const en_4: {
+    "link.javascript-protocol": string;
+    "link.unsupported-protocol": string;
+    "link.malformed-mailto": string;
+    "link.malformed-tel": string;
+    "link.localhost-or-staging": string;
 };
 
 /**
@@ -115,6 +114,8 @@ export declare function extractAnchors(html: string): AnchorInfo[];
  */
 export declare function extractText(html: string): string;
 
+export declare function formatLinkMessage(locale: string, ruleId: LinkRuleMessageId, params?: Record<string, string | number>): string;
+
 /**
  * Resolve a localized message for a rule. `params` interpolate `{name}`
  * placeholders. Falls back to English when the locale doesn't ship the
@@ -122,6 +123,8 @@ export declare function extractText(html: string): string;
  */
 export declare function formatMessage(locale: string, ruleId: RuleMessageId, params?: Record<string, string | number>): string;
 
+export declare function formatStructureMessage(locale: string, ruleId: StructureRuleMessageId, params?: Record<string, string | number>): string;
+
 /**
  * WCAG 2.1 sRGB relative-luminance contrast.
  *
@@ -145,20 +148,116 @@ export declare function getContrastRatio(fg: string, bg: string): number;
  */
 export declare function getDictionary(_locale: string): Dictionary;
 
+export declare function getLinkMessages(locale: string): LinkMessageMap;
+
 export declare function getMessages(locale: string): MessageMap;
 
+export declare function getStructureMessages(locale: string): StructureMessageMap;
+
+/**
+ * `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 function lintAccessibility(content: TemplateContent, options?: A11yOptions): A11yIssue[];
+export declare const LINK_RULES: Rule[];
+
+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 {
+    /** Block id, or null for template-level issues. */
+    blockId: string | null;
+    ruleId: string;
+    severity: Exclude<Severity, "off">;
+    message: string;
+    fix?: LintPatch;
+}
+
+export declare function lintLinks(content: TemplateContent, options?: LintOptions): LintIssue[];
+
+export declare interface LintOptions {
+    /**
+     * Fully disable linting. When true, the editor skips lazy-loading the
+     * package, hides the sidebar tab, and suppresses inline badges.
+     */
+    disabled?: boolean;
+    /** Locale for vague-text dictionaries and message text. Falls back to `en`. */
+    locale?: string;
+    /**
+     * 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 {
+    description: string;
+    apply: (ctx: LintPatchContext) => void;
+}
+
+export declare interface LintPatchContext {
+    updateBlock: (blockId: string, patch: Partial<Block>) => void;
+    updateSettings: (patch: Partial<TemplateSettings>) => void;
+    removeBlock: (blockId: string) => void;
+}
+
+export declare function lintStructure(content: TemplateContent, options?: LintOptions): LintIssue[];
+
+export declare interface LintThresholds {
+    altMaxLength: number;
+    minFontSize: number;
+    allCapsMinLength: number;
+    minTouchTargetPx: number;
+}
 
 export declare type MessageMap = typeof en_2;
 
 export declare function parseHex(input: string | undefined | null): Rgb | null;
 
+export declare interface ResolvedLinksOptions {
+    nonProductionHosts: string[];
+}
+
 export declare interface ResolvedOptions {
     locale: string;
-    rules: Record<string, Severity>;
-    thresholds: A11yThresholds;
+    rules: RuleOverrides;
+    thresholds: LintThresholds;
+    links: ResolvedLinksOptions;
     /** Returns the effective severity for a rule (override or default). */
     severity: (ruleId: string) => Severity;
 }
@@ -186,7 +285,7 @@ export declare interface RuleHit {
     blockId: string | null;
     /** Interpolation values for the rule's localized message template. */
     params?: Record<string, string | number>;
-    fix?: A11yPatch;
+    fix?: LintPatch;
 }
 
 export declare type RuleMessageId = keyof MessageMap;
@@ -198,14 +297,44 @@ export declare interface RuleMeta {
     severity: Exclude<Severity, "off">;
 }
 
-export declare const RULES: Rule[];
+/**
+ * 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;
+
 export declare const SUPPORTED_DICTIONARY_LOCALES: string[];
 
+export declare const SUPPORTED_LINK_MESSAGE_LOCALES: string[];
+
 export declare const SUPPORTED_MESSAGE_LOCALES: string[];
 
+export declare const SUPPORTED_STRUCTURE_MESSAGE_LOCALES: string[];
+
+export declare interface UrlOccurrence {
+    url: string;
+    blockId: string;
+    source: UrlSource;
+    /** Anchor text or block-derived label, if applicable. */
+    label?: string;
+}
+
+export declare type UrlSource = "anchor" | "button" | "image-link" | "video" | "menu-item" | "social-icon";
+
 export declare type Visitor = (block: Block, ctx: WalkContext) => void;
 
 /**
@@ -231,4 +360,20 @@ export declare interface WalkContext {
     resolvedBackgroundColor: string;
 }
 
+/**
+ * Visit every URL-bearing field in the template tree.
+ *
+ * Sources covered:
+ *  - anchor      — `<a href>` inside `title.content`, `paragraph.content`,
+ *                  `html.content` (parsed via extractAnchors)
+ *  - button      — `button.url`
+ *  - image-link  — `image.linkUrl` (only when present + non-empty)
+ *  - video       — `video.url`
+ *  - menu-item   — `menu.items[i].url`
+ *  - social-icon — `social.icons[i].url`
+ *
+ * Each rule iterates this list once and decides per occurrence.
+ */
+export declare function walkUrls(content: TemplateContent_2): UrlOccurrence[];
+
 export { }