@bridge-ds/core 0.3.0 → 0.5.0

package/README.md

@@ -297,12 +297,12 @@ conflicts table.
 ## audit (`@bridge-ds/core/audit`)
 
 Design system adoption and drift in a product codebase that consumes the DS. Pure (file texts in, report
-out); it reads TSX/JSX with the TypeScript compiler API (syntax only), which is why it is its own entry and the
-Figma plugin never loads it. `@bridge-ds/core/node` adds the disk side.
+out); it reads TSX/JSX, and the frontmatter and scripts of Astro, Vue and Svelte files, with the TypeScript
+compiler API (syntax only), which is why it is its own entry and the Figma plugin never loads it. `@bridge-ds/core/node` adds the disk side.
 
 ```ts
 import { DesignSystemIndex, buildAuditReport, compareWithBaseline, auditMarkdown, planCssFixes, auditFile } from '@bridge-ds/core/audit';
-import { loadDesignSystem, runAudit, collectAuditFiles, fixCss, findDesignSystemRoot } from '@bridge-ds/core/node';
+import { loadDesignSystem, runAudit, collectAuditFiles, fixCss, findDesignSystemRoot, loadAllowlist } from '@bridge-ds/core/node';
 
 const ds = loadDesignSystem('/path/to/ds-repo');               // bridge.config.json: tokens in every mode, components, packages
 const report = runAudit('apps/admin/src', { ds: ds.root, label: 'admin', baseline });  // AuditReport, schemaVersion 1
@@ -310,7 +310,9 @@ const report = runAudit('apps/admin/src', { ds: ds.root, label: 'admin', baselin
 
 - **Scanned**: CSS, SCSS, Less, CSS modules; `style`, MUI `sx`, `styled()`, `makeStyles`, `createTheme` and theme
   objects, styled-components / emotion templates; Tailwind class strings (`className`, `cn()`, `clsx()`, `cva()`,
-  `@apply`); any color literal in code.
+  `@apply`); any color literal in code. Astro, Vue and Svelte files: the frontmatter and `<script>` blocks as
+  TS, `<style>` blocks as CSS/SCSS/Less, and the template markup (tags, `style` and `class` attributes, static
+  `style="..."`, `style={{ ... }}`, Vue `:style`, Svelte `style:prop`, color attributes such as `fill="#..."`).
 - **Hardcoded values**: colors (hex, rgb, hsl, named, bare HSL channels), spacing, sizes, radii, border widths,
   shadows, durations, easings, z-index, font family, size, weight and line height. Each gets the closest token:
   colors by deltaE in OKLab across every mode (semantic tokens and tokens that fit the property win near-ties),
@@ -323,7 +325,16 @@ const report = runAudit('apps/admin/src', { ds: ds.root, label: 'admin', baselin
   (`button`, `input`, `select`, `textarea`, `dialog`, `table`, `a` with `href`, `img`), router links (react-router,
   ra-core `LinkBase`, next/link) unless passed as a DS component's `render` element, chart libraries (recharts,
   Nivo, Chart.js...: foreign with no DS equivalent) and local components named like a DS component. Providers and
-  other non-visual parts never count, DS ones included.
+  other non-visual parts never count, DS ones included. In Astro, Vue and Svelte templates a tag is a DS component
+  when the frontmatter or `<script>` imports it from a DS package (Vue kebab case `<ds-button>` included); a local
+  `Button.astro`, `Button.vue` or `Button.svelte` is a re-created DS component. `<input type="hidden">`, anchors
+  without `href` and anything inside `<noscript>` are not UI instances.
+- **Escape hatches**: `bridge-audit-ignore-next-line: reason` in any comment (`<!-- -->`, `{/* */}`, `/* */`,
+  `//`) leaves the findings of the next line out of the counts. The reason is required: without one, or when the
+  next line has no finding, nothing is ignored and the file lists it under `ignoreErrors`. An allowlist
+  (`runAudit(..., { allowlist: loadAllowlist(path) })`, `{ "entries": [{ "file", "line", "what"?, "reason" }] }`) does
+  the same for known file:line violations. Ignored items stay in the report (`files[].ignored`, `ignored.items`),
+  with their reason; allowlist entries that match nothing are listed in `ignored.staleAllowlist`.
 - **Metrics**: token adoption = token references / (token references + hardcoded values); component adoption =
   DS instances / all UI instances. By category, top files, top fixes, per-file findings with line numbers.
 - **Baseline**: `compareWithBaseline(report, previous)` adds deltas per metric, category and file, and carries the

package/audit-report.schema.json

@@ -358,6 +358,43 @@
     "baseline": {
       "$ref": "#/$defs/baseline"
     },
+    "ignored": {
+      "type": "object",
+      "description": "What was left out of the counts on purpose, and allowlist entries that match nothing any more.",
+      "required": [
+        "total",
+        "comment",
+        "allowlist",
+        "items",
+        "staleAllowlist"
+      ],
+      "properties": {
+        "total": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "comment": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "allowlist": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "items": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/ignored"
+          }
+        },
+        "staleAllowlist": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/allowlistEntry"
+          }
+        }
+      }
+    },
     "history": {
       "type": "array",
       "items": {
@@ -438,7 +475,10 @@
             "tsx",
             "jsx",
             "ts",
-            "js"
+            "js",
+            "astro",
+            "vue",
+            "svelte"
           ]
         },
         "tokenUsages": {
@@ -563,6 +603,32 @@
               }
             }
           }
+        },
+        "ignored": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/ignored"
+          }
+        },
+        "ignoreErrors": {
+          "type": "array",
+          "description": "bridge-audit-ignore-next-line comments that ignored nothing (no reason, or nothing on the next line).",
+          "items": {
+            "type": "object",
+            "required": [
+              "line",
+              "message"
+            ],
+            "properties": {
+              "line": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "message": {
+                "type": "string"
+              }
+            }
+          }
         }
       }
     },
@@ -727,6 +793,74 @@
           "minimum": 0
         }
       }
+    },
+    "ignored": {
+      "type": "object",
+      "description": "A finding or component left out of the counts on purpose, kept in the report so it stays visible.",
+      "required": [
+        "line",
+        "column",
+        "kind",
+        "what",
+        "reason",
+        "via"
+      ],
+      "properties": {
+        "line": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "column": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "kind": {
+          "enum": [
+            "value",
+            "component"
+          ]
+        },
+        "what": {
+          "type": "string",
+          "description": "The value as written or the element or component name."
+        },
+        "reason": {
+          "type": "string"
+        },
+        "via": {
+          "enum": [
+            "comment",
+            "allowlist"
+          ],
+          "description": "A bridge-audit-ignore-next-line comment, or an allowlist entry."
+        },
+        "file": {
+          "type": "string"
+        }
+      }
+    },
+    "allowlistEntry": {
+      "type": "object",
+      "required": [
+        "file",
+        "line",
+        "reason"
+      ],
+      "properties": {
+        "file": {
+          "type": "string"
+        },
+        "line": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "what": {
+          "type": "string"
+        },
+        "reason": {
+          "type": "string"
+        }
+      }
     }
   }
 }

package/dist/audit/code.d.ts

@@ -1,3 +1,4 @@
+import { type TailwindHit } from './tailwind';
 import type { DesignSystemIndex } from './ds-index';
 import type { ComponentFinding, StyleFinding } from './types';
 export interface CodeScan {
@@ -13,4 +14,53 @@ export interface CodeScan {
         line: number;
     }[];
 }
+/** The DS component a DOM renderer stands for: `checklistRowHtml` -> ChecklistRow, else the longest DS name it starts with. */
+export declare function domRendererComponent(fn: string, components: Set<string>): string | undefined;
+/**
+ * Homemade look-alikes in markup a script builds (`class="pill"`, `data-tip="..."`): the DS component they imitate.
+ * Exact class tokens only, so app classes that merely contain the word (`cm-pill-row`) are not counted.
+ */
+export declare const LOOKALIKE_CLASSES: Record<string, string>;
+export declare const LOOKALIKE_ATTRS: Record<string, string>;
+/** Look-alikes in a class list (`pill is-pass`): one finding per imitated component. */
+export declare function lookalikesInClassList(list: string, components: Set<string>): {
+    token: string;
+    component: string;
+}[];
+/** Imported name -> module and exported name ('default', '*' for a namespace). */
+export type ImportMap = Map<string, {
+    module: string;
+    imported: string;
+}>;
+/** Import declarations of a script (TS or JS), for markup files whose tags use what the script imports. */
+export declare function importsOf(path: string, text: string): ImportMap;
+/** One element as written in JSX or in a template (Astro, Vue, Svelte). */
+export interface TagUse {
+    name: string;
+    line: number;
+    column: number;
+    /** Static `type` attribute. */
+    type?: string;
+    hasHref: boolean;
+    /** The element only gives a component its tag or router (`render={<a href="/x" />}`). */
+    inRenderProp?: boolean;
+}
+/**
+ * What an element is: a DS component instance, a foreign, native or re-created component, or nothing (providers,
+ * hidden inputs, anchors without href). `localCandidate`: an unimported DS-named tag, re-created only when the file
+ * defines it.
+ */
+export declare function classifyTag(t: TagUse, imports: ImportMap, ds: DesignSystemIndex): {
+    ds?: string;
+    component?: ComponentFinding;
+    localCandidate?: ComponentFinding;
+};
+/** Findings for Tailwind classes (arbitrary values and palette classes); scale classes count as theme references. */
+export declare function tailwindFindings(hits: TailwindHit[], offset: number, pos: (offset: number) => {
+    line: number;
+    column: number;
+}, ds: DesignSystemIndex): {
+    findings: StyleFinding[];
+    themeRefs: number;
+};
 export declare function scanCode(path: string, text: string, ds: DesignSystemIndex): CodeScan;

package/dist/audit/ignore.d.ts

@@ -0,0 +1,34 @@
+import type { AllowlistEntry, ComponentFinding, IgnoredItem, StyleFinding } from './types';
+export declare const IGNORE_DIRECTIVE = "bridge-audit-ignore-next-line";
+export interface IgnoreDirective {
+    /** Line of the comment (1-based). */
+    line: number;
+    /** Line it applies to: the one after the comment ends. */
+    target: number;
+    /** Empty when the comment gives none: such a comment ignores nothing. */
+    reason: string;
+}
+/**
+ * Every `bridge-audit-ignore-next-line` comment in a file: `<!-- ...: reason -->` (HTML, Astro, Vue, Svelte),
+ * `{/* ...: reason *\/}` (JSX, Astro expressions), `/* ...: reason *\/` (CSS) and `// ...: reason` (scripts).
+ * The text after the colon is the reason. A mention outside a comment is not a directive.
+ */
+export declare function ignoreDirectives(text: string): IgnoreDirective[];
+export interface IgnoreResult {
+    findings: StyleFinding[];
+    components: ComponentFinding[];
+    ignored: IgnoredItem[];
+}
+/** Apply the file's ignore comments. Comments without a reason, or that match nothing, are reported as errors. */
+export declare function applyIgnoreComments(text: string, findings: StyleFinding[], components: ComponentFinding[]): IgnoreResult & {
+    errors: {
+        line: number;
+        message: string;
+    }[];
+};
+/** Apply allowlist entries for one file; returns what each entry matched (index in `entries`). */
+export declare function applyAllowlist(entries: AllowlistEntry[], findings: StyleFinding[], components: ComponentFinding[]): IgnoreResult & {
+    used: Set<number>;
+};
+/** Validate an allowlist file's JSON: `{ "entries": [{ "file", "line", "what"?, "reason" }] }`, a reason on each entry. */
+export declare function parseAllowlist(json: unknown): AllowlistEntry[];

package/dist/audit/index.d.ts

@@ -7,3 +7,6 @@ export * from './components';
 export * from './ds-index';
 export * from './code';
 export * from './report';
+export * from './style';
+export * from './ignore';
+export * from './markup';

package/dist/audit/index.js

@@ -1,4 +1,4 @@
-import { A, a, b, C, D, c, F, N, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x, y, z, B, E, G, H, I } from "../report-tNzTriGF.js";
+import { A, a, b, C, D, c, F, I, L, d, M, N, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x, y, z, B, E, G, H, J, K, O, P, Q, R, S, T, U, V, W, X, Y, Z } from "../report-4Z008HSf.js";
 export {
   A as AUDIT_EXTENSIONS,
   a as AUDIT_IGNORE_DIRS,
@@ -7,34 +7,50 @@ export {
   D as DEFAULT_NATIVE_ELEMENTS,
   c as DesignSystemIndex,
   F as FINDING_CATEGORIES,
+  I as IGNORE_DIRECTIVE,
+  L as LOOKALIKE_ATTRS,
+  d as LOOKALIKE_CLASSES,
+  M as MARKUP_EXTENSIONS,
   N as NAMED_COLORS,
-  d as auditFile,
-  e as auditMarkdown,
-  f as blankComments,
-  g as buildAuditReport,
-  h as classifyModule,
-  i as compareWithBaseline,
-  j as cssPropertyOf,
-  k as deltaE,
-  l as dsEquivalent,
-  m as historyPoint,
-  n as isAuditable,
-  o as isColorLiteral,
-  p as isNonVisual,
-  q as isRouterLink,
-  r as isSafeFix,
-  s as libraryLabel,
-  t as lineCol,
-  u as nativeEquivalent,
-  v as packageName,
-  w as parseCssColor,
-  x as planCssFixes,
-  y as scanClassString,
-  z as scanCode,
-  B as scanCssText,
-  E as scanCssValue,
-  G as scanJsStyle,
-  H as tailwindColor,
-  I as toOklab
+  e as applyAllowlist,
+  f as applyIgnoreComments,
+  g as auditCssText,
+  h as auditFile,
+  i as auditMarkdown,
+  j as blankComments,
+  k as buildAuditReport,
+  l as classifyModule,
+  m as classifyTag,
+  n as compareWithBaseline,
+  o as cssPropertyOf,
+  p as deltaE,
+  q as domRendererComponent,
+  r as dsEquivalent,
+  s as historyPoint,
+  t as ignoreDirectives,
+  u as importsOf,
+  v as isAuditable,
+  w as isColorLiteral,
+  x as isNonVisual,
+  y as isRouterLink,
+  z as isSafeFix,
+  B as libraryLabel,
+  E as lineCol,
+  G as lookalikesInClassList,
+  H as markupBlocks,
+  J as nativeEquivalent,
+  K as packageName,
+  O as parseAllowlist,
+  P as parseCssColor,
+  Q as planCssFixes,
+  R as scanClassString,
+  S as scanCode,
+  T as scanCssText,
+  U as scanCssValue,
+  V as scanJsStyle,
+  W as scanMarkup,
+  X as tailwindColor,
+  Y as tailwindFindings,
+  Z as toOklab
 };
 //# sourceMappingURL=index.js.map

package/dist/audit/markup.d.ts

@@ -0,0 +1,21 @@
+import { type CodeScan } from './code';
+import type { DesignSystemIndex } from './ds-index';
+export type MarkupLang = 'astro' | 'vue' | 'svelte';
+export declare const MARKUP_EXTENSIONS: string[];
+interface Range {
+    start: number;
+    end: number;
+}
+interface Block extends Range {
+    attrs: string;
+}
+/** Frontmatter (Astro), script and style blocks, and the template ranges between them. */
+export declare function markupBlocks(text: string, lang: MarkupLang): {
+    frontmatter?: Range;
+    scripts: Block[];
+    styles: Block[];
+    nonTemplate: Range[];
+};
+/** Audit an Astro, Vue or Svelte file. Line and column numbers are the file's own. */
+export declare function scanMarkup(path: string, text: string, lang: MarkupLang, ds: DesignSystemIndex): CodeScan;
+export {};

package/dist/audit/report.d.ts

@@ -1,14 +1,9 @@
 import type { DesignSystemIndex } from './ds-index';
-import { type AuditReport, type FileReport, type FindingCategory, type HistoryPoint, type TokenSuggestion } from './types';
+import { type AuditReport, type FileReport, type AllowlistEntry, type HistoryPoint } from './types';
 export declare const AUDIT_EXTENSIONS: string[];
 export declare const AUDIT_IGNORE_DIRS: string[];
 /** Should the audit read this repo-relative path? */
 export declare function isAuditable(path: string): boolean;
-/** A literal the CSS autofix may replace: exact token value, same spelling for lengths and durations. */
-export declare function isSafeFix(h: {
-    category: FindingCategory;
-    text: string;
-}, s: TokenSuggestion | undefined): boolean;
 export type AuditedFile = FileReport & {
     definitions: {
         name: string;
@@ -16,7 +11,7 @@ export type AuditedFile = FileReport & {
     }[];
     dsByName: Record<string, number>;
 };
-/** Audit one file. */
+/** Audit one file. `bridge-audit-ignore-next-line: reason` comments leave the next line's findings out of the counts. */
 export declare function auditFile(path: string, text: string, ds: DesignSystemIndex): AuditedFile;
 export interface AuditInput {
     files: {
@@ -28,6 +23,8 @@ export interface AuditInput {
     label?: string;
     version?: string;
     generatedAt?: string;
+    /** Known violations left out of the counts, each with a reason (an allowlist file, see parseAllowlist). */
+    allowlist?: AllowlistEntry[];
 }
 /** Build the report for a set of files. */
 export declare function buildAuditReport(input: AuditInput, ds: DesignSystemIndex): AuditReport;
@@ -38,6 +35,7 @@ export declare function compareWithBaseline(report: AuditReport, baseline: Audit
 export declare function auditMarkdown(r: AuditReport, opts?: {
     topFiles?: number;
     topFixes?: number;
+    ignored?: number;
 }): string;
 export interface CssFixEdit {
     line: number;

package/dist/audit/style.d.ts

@@ -0,0 +1,25 @@
+import type { DesignSystemIndex } from './ds-index';
+import type { FindingCategory, FindingSource, StyleFinding, TokenSuggestion } from './types';
+/** A literal the CSS autofix may replace: exact token value, same spelling for lengths and durations. */
+export declare function isSafeFix(h: {
+    category: FindingCategory;
+    text: string;
+}, s: TokenSuggestion | undefined): boolean;
+export interface CssAudit {
+    findings: StyleFinding[];
+    tokenUsages: number;
+    themeRefs: number;
+}
+/**
+ * Audit style sheet text. `offset` places the text inside a larger file (a <style> block, a style attribute) and
+ * `pos` maps a file offset to its line and column. `source` labels the findings (`css` for sheets, `style` for
+ * style attributes); only `css` findings are marked for the autofix, which rewrites CSS files.
+ */
+export declare function auditCssText(text: string, lang: 'css' | 'scss' | 'less', ds: DesignSystemIndex, opts: {
+    pos: (offset: number) => {
+        line: number;
+        column: number;
+    };
+    offset?: number;
+    source?: FindingSource;
+}): CssAudit;

package/dist/audit/types.d.ts

@@ -48,7 +48,7 @@ export interface ComponentFinding {
 export interface FileReport {
     /** Path relative to the audited root, with forward slashes. */
     path: string;
-    lang: 'css' | 'scss' | 'less' | 'tsx' | 'jsx' | 'ts' | 'js';
+    lang: 'css' | 'scss' | 'less' | 'tsx' | 'jsx' | 'ts' | 'js' | 'astro' | 'vue' | 'svelte';
     tokenUsages: number;
     /** References to another theme (MUI theme, Tailwind scale classes): not hardcoded, not the DS either. */
     themeRefs: number;
@@ -58,6 +58,34 @@ export interface FileReport {
     otherComponents: number;
     findings: StyleFinding[];
     components: ComponentFinding[];
+    /** Findings and components left out of the counts on purpose, each with its reason. */
+    ignored?: IgnoredItem[];
+    /** `bridge-audit-ignore-next-line` comments that ignored nothing because they give no reason. */
+    ignoreErrors?: {
+        line: number;
+        message: string;
+    }[];
+}
+/** Where an ignore comes from: an escape-hatch comment in the file, or an entry of the allowlist file. */
+export type IgnoreVia = 'comment' | 'allowlist';
+/** A finding or component the audit saw but does not count, kept in the report so it stays visible. */
+export interface IgnoredItem {
+    line: number;
+    column: number;
+    kind: 'value' | 'component';
+    /** The value as written ("13px") or the element or component name ("select"). */
+    what: string;
+    reason: string;
+    via: IgnoreVia;
+}
+/** One entry of an allowlist file: a known violation, left out of the counts for a stated reason. */
+export interface AllowlistEntry {
+    /** Path relative to the audited folder, as in the report. */
+    file: string;
+    line: number;
+    /** Element, component or value on that line ("select", "13px"). Absent: everything on the line. */
+    what?: string;
+    reason: string;
 }
 export interface CategoryCount {
     hardcoded: number;
@@ -176,6 +204,16 @@ export interface AuditReport {
     topFixes: TopFix[];
     files: FileReport[];
     baseline?: BaselineDiff;
+    /** What was left out of the counts on purpose (escape-hatch comments, allowlist), and allowlist entries that match nothing. */
+    ignored?: {
+        total: number;
+        comment: number;
+        allowlist: number;
+        items: (IgnoredItem & {
+            file: string;
+        })[];
+        staleAllowlist: AllowlistEntry[];
+    };
     /** Earlier runs, oldest first (carried over from the baseline). */
     history: HistoryPoint[];
 }