@designtools/adherence 0.0.0-stage → 0.1.1

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+import {
+  UsageError,
+  VERSION,
+  buildReport,
+  formatMarkdown,
+  loadConfig,
+  serialise
+} from "./chunk-7FM4ZQLW.js";
+
+// src/cli.ts
+import { mkdirSync, writeFileSync } from "fs";
+import { dirname, resolve } from "path";
+import { parseArgs } from "util";
+var HELP = `designtools-adherence ${VERSION}
+
+How closely a product follows its design system: how much of what a system
+component could render comes from the system, which classes bypass the tokens,
+and where a component's className fights its variants. Warnings only: it exits
+0 whatever it finds.
+
+Usage
+  designtools-adherence                    Print a markdown report, for a pull request comment
+  designtools-adherence --format json      Print the JSON report
+  designtools-adherence --json report.json Also write the JSON report to a file
+
+Options
+  --manifest <file>    The components.json to read (default: from designtools.json)
+  --include <glob>     Product files to scan; repeat for each (default: app/** and src/**)
+  --exclude <glob>     Files to leave out, on top of the system folder, app/design, app/(design),
+                       tests, fixtures, examples and stories; repeat for each
+  --format <md|json>   What to print (default: md)
+  --json <file>        Write the JSON report to a file as well
+  --root <dir>         Project root (default: the current directory)
+  --timings            Print how long each stage took, to stderr
+  -h, --help           Show this help
+  -v, --version        Show the version
+
+It reads the manifest that designtools-manifest builds, found from designtools.json:
+  { "manifest": { "system": "src/ds" }, "adherence": { "exclude": ["app/legacy/**"] } }
+`;
+function fail(message) {
+  process.stderr.write(`designtools-adherence: ${message}
+`);
+  process.exit(2);
+}
+var args;
+function parse() {
+  return parseArgs({
+    allowPositionals: false,
+    options: {
+      manifest: { type: "string" },
+      include: { type: "string", multiple: true },
+      exclude: { type: "string", multiple: true },
+      format: { type: "string" },
+      json: { type: "string" },
+      root: { type: "string" },
+      timings: { type: "boolean" },
+      help: { type: "boolean", short: "h" },
+      version: { type: "boolean", short: "v" }
+    }
+  });
+}
+try {
+  args = parse();
+} catch (e) {
+  fail(`${e.message}
+
+${HELP}`);
+}
+var { values } = args;
+if (values.help) {
+  process.stdout.write(HELP);
+  process.exit(0);
+}
+if (values.version) {
+  process.stdout.write(`${VERSION}
+`);
+  process.exit(0);
+}
+var format = values.format ?? "md";
+if (format !== "md" && format !== "json") fail(`--format must be md or json`);
+var config;
+try {
+  config = loadConfig({ root: values.root, manifest: values.manifest, include: values.include, exclude: values.exclude });
+} catch (e) {
+  fail(e.message);
+}
+var built;
+try {
+  built = await buildReport(config);
+} catch (e) {
+  if (e instanceof UsageError) fail(e.message);
+  process.stderr.write(`designtools-adherence: could not finish the report: ${e.message}
+`);
+  process.exit(0);
+}
+var json = serialise(built.report);
+if (values.json) {
+  const path = resolve(values.json);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, json);
+}
+process.stdout.write(format === "json" ? json : formatMarkdown(built.report));
+if (values.timings) {
+  const t = built.timings;
+  const ms = (n) => `${Math.round(n)}ms`;
+  process.stderr.write(
+    `timings: files ${ms(t.files)}, components ${ms(t.components)}, discipline ${ms(t.discipline)}, total ${ms(t.total)} (${built.report.summary.files} files)
+`
+  );
+}
+process.exit(0);

package/dist/index.d.ts

@@ -0,0 +1,473 @@
+/**
+ * Configuration: `designtools.json` at the project root, overridden by flags.
+ *
+ *   {
+ *     "manifest": { "system": "src/ds" },
+ *     "adherence": { "include": ["app/**", "src/**"], "exclude": ["app/legacy/**"] }
+ *   }
+ *
+ * The manifest section says where components.json is (`out`, or `<system>/manifest`),
+ * which is all adherence needs: the system's components, sources and replaced
+ * elements all come from there.
+ */
+declare const CONFIG_FILE = "designtools.json";
+/** The report cannot run as asked: no manifest, an unreadable one, a bad setting. The CLI exits 2. */
+declare class UsageError extends Error {
+}
+/** Product source, by default: the app router and src, whatever the system folder is. */
+declare const DEFAULT_INCLUDE: string[];
+/**
+ * Never product, whatever `--include` says: the system folder is added at run
+ * time, the docs pages, tests, fixtures, examples, stories and type declarations.
+ */
+declare const DEFAULT_EXCLUDE: string[];
+interface AdherenceConfig {
+    /** Project root, absolute. Every other path is relative to it. */
+    root: string;
+    /** components.json, relative to root (or absolute when it lives outside it). */
+    manifest: string;
+    /** tokens.json beside it; absent when there is none. */
+    tokens?: string;
+    /** tsconfig.json for path aliases; found at the root when absent. */
+    tsconfig?: string;
+    include: string[];
+    /** The defaults, the system folder, and anything added. */
+    exclude: string[];
+}
+interface ConfigFlags {
+    root?: string;
+    /** A components.json to read instead of the one designtools.json points at. */
+    manifest?: string;
+    include?: string[];
+    exclude?: string[];
+}
+declare function loadConfig(flags: ConfigFlags): AdherenceConfig;
+
+/**
+ * The adherence report: what `designtools-adherence` writes with `--json`, and
+ * what the "Adherence summary" docs block renders.
+ *
+ * This file has no imports on purpose, so @designtools/blocks can carry a copy
+ * and read the report through the same types the tool wrote it with.
+ *
+ * Every path is relative to the project root, with forward slashes. Lines and
+ * columns start at 1. Every array is sorted (files and routes by path, findings
+ * by line then column, components and elements by name), and there are no
+ * timestamps, so the same source gives the same bytes.
+ */
+declare const ADHERENCE_SCHEMA = "designtools.adherence/1";
+interface AdherenceReport {
+    /** `@designtools/adherence@<version>`. */
+    generator: string;
+    schema: string;
+    /** The components.json the system was read from. */
+    manifest: string;
+    /** The system folder, which is never scanned as product. */
+    system: string;
+    /** The globs that chose the product files, as given or defaulted. */
+    include: string[];
+    exclude: string[];
+    summary: Summary;
+    /** One per Next app router page (`app/**\/page.tsx`), sorted by route. */
+    routes: RouteEntry[];
+    /** Every scanned file with at least one use, raw element or finding, sorted by path. */
+    files: FileEntry[];
+    /** Every system component, used or not, sorted by name. */
+    components: ComponentUsage[];
+    /** Every raw element some component `replaces`, sorted by selector. */
+    elements: ElementUsage[];
+    /** Files a scanner could not parse, sorted by path. Their numbers are missing from the report. */
+    skipped: SkippedFile[];
+}
+/** The numbers every level of the report shares: the whole product, a route, a file. */
+interface Counts {
+    /** JSX uses of system components, sub-components included. */
+    systemUses: number;
+    /** Raw elements that some system component `replaces`, such as `<button>` when Button replaces it. */
+    rawElements: number;
+    /**
+     * systemUses ÷ (systemUses + rawElements), from 0 to 1, to four decimal places.
+     * Null when both are 0: there was nothing to measure.
+     */
+    share: number | null;
+    /** Classes that bypass the tokens: palette steps and arbitrary values. */
+    offSystemValues: number;
+    /** System components given a className that changes colour, spacing or radius. */
+    overrides: number;
+}
+interface Summary extends Counts {
+    /** Product files scanned. */
+    files: number;
+    /** Files with at least one raw element, off-system value or override. */
+    filesWithFindings: number;
+    offSystem: Record<OffSystemKind, number>;
+    overrideKinds: Record<OverrideKind, number>;
+    /** System components used at least once. */
+    componentsUsed: number;
+    /** System components never used in the product, by name. */
+    componentsUnused: string[];
+    /**
+     * The raw elements counted, from every component's `replaces`. Empty means no
+     * component declares any, so `share` measures nothing yet.
+     */
+    replaceable: string[];
+}
+interface RouteEntry {
+    /** The URL path: route groups and parallel-route slots removed, dynamic segments kept. `/companies/[key]`. */
+    route: string;
+    /** The page file. */
+    page: string;
+    /**
+     * The files counted for the route: the page, files beside it, and files in
+     * folders under it that lead to no other page. Layouts shared by several
+     * routes are counted per file only.
+     */
+    files: string[];
+    counts: Counts;
+}
+interface FileEntry {
+    file: string;
+    /** The route the file is counted under, when it has one. */
+    route?: string;
+    counts: Counts;
+    uses: ComponentUse[];
+    raw: RawElement[];
+    offSystem: OffSystemValue[];
+    overrides: Override[];
+}
+/** A literal prop value, or the kind of expression it was, e.g. `(Identifier)`. */
+type PropValue = string | number | boolean | null;
+interface ComponentUse {
+    /** The component's name in the manifest. */
+    component: string;
+    /** The element as written, when it differs: `Select.Trigger`, `DS.Button`. */
+    as?: string;
+    line: number;
+    column: number;
+    /** Props as written, sorted. A className built from expressions keeps its literal classes only. */
+    props: Record<string, PropValue>;
+    /** True when it also takes `{...spread}` props, whose names are unknown. */
+    spread: boolean;
+}
+interface RawElement {
+    /** The tag as written: `button`. */
+    element: string;
+    /** The `replaces` selector it matched: `button`, `input[type=checkbox]`. */
+    selector: string;
+    /** The components that replace it, most specific first. */
+    replacedBy: string[];
+    line: number;
+    column: number;
+}
+/**
+ * `palette`: a primitive ramp step used directly, `bg-blue-500` or `text-primary-500`.
+ * `arbitrary`: a value in brackets, `p-[13px]` or `bg-[#fff]`.
+ * `status-text`: a status fill used as text, `text-destructive`: use `text-destructive-subdued-foreground`,
+ * which reads on every background, or neutral text with an icon for a warning.
+ */
+type OffSystemKind = "palette" | "arbitrary" | "status-text";
+interface OffSystemValue {
+    /** The class as written, variants included: `hover:bg-blue-500`. */
+    class: string;
+    kind: OffSystemKind;
+    line: number;
+    column: number;
+}
+type OverrideKind = "colour" | "spacing" | "radius";
+interface Override {
+    component: string;
+    /** Each class in the className that overrides the component, with what it changes. */
+    classes: {
+        class: string;
+        kind: OverrideKind;
+    }[];
+    line: number;
+    column: number;
+}
+interface ComponentUsage {
+    name: string;
+    source: string;
+    uses: number;
+    /** Files it is used in. */
+    files: number;
+    /** How many uses pass each prop, by prop name. */
+    props: Record<string, number>;
+    /**
+     * Per variant axis, how many uses pick each option. A use that leaves the prop
+     * out counts under the axis's default, or `(unset)`; one that computes it
+     * counts under `(dynamic)`.
+     */
+    variants?: Record<string, Record<string, number>>;
+}
+interface ElementUsage {
+    /** The `replaces` selector. */
+    selector: string;
+    /** Raw uses in the product. */
+    uses: number;
+    files: number;
+    replacedBy: string[];
+}
+interface SkippedFile {
+    file: string;
+    reason: string;
+}
+
+/**
+ * Build the adherence report in memory. Nothing here writes to disk; nothing
+ * here decides an exit code. Every finding is a warning.
+ */
+
+declare const GENERATOR_NAME = "@designtools/adherence";
+declare const VERSION: string;
+declare const GENERATOR: string;
+interface Timings {
+    files: number;
+    components: number;
+    discipline: number;
+    total: number;
+}
+interface BuiltReport {
+    report: AdherenceReport;
+    /** Milliseconds per stage, for the CLI's `--timings`; never part of the report. */
+    timings: Timings;
+}
+declare function buildReport(config: AdherenceConfig): Promise<BuiltReport>;
+declare function counts(systemUses: number, rawElements: number, offSystemValues: number, overrides: number): Counts;
+/** The report as committed or posted: two-space JSON with a trailing newline. */
+declare function serialise(report: AdherenceReport): string;
+
+/**
+ * The report as markdown, for a pull request comment. Kept under GitHub's
+ * comment limit: past it, files are cut and the JSON report has the rest.
+ */
+
+declare function formatMarkdown(report: AdherenceReport): string;
+
+/**
+ * Which files are product: walk from each include glob's base, keep what an
+ * include matches and no exclude does. One list feeds both scanners, so they
+ * always agree on what was looked at.
+ */
+declare function listProductFiles(root: string, includeGlobs: string[], excludeGlobs: string[]): string[];
+
+/**
+ * Next app router pages to routes, and product files to the route they count under.
+ *
+ * A page is `app/**\/page.{tsx,jsx,ts,js,mdx}` (or under `src/app`). Its route
+ * drops route groups `(group)`, parallel-route slots `@slot` and the `(.)`
+ * of an intercepting segment, and keeps dynamic segments as written.
+ *
+ * A file counts under the nearest page above it, as long as no folder on the
+ * way leads to another page: a page's own
+ * components, private `_folders` and loading or error files count with it;
+ * a layout in a group folder shared by several pages counts per file only.
+ */
+interface Routes {
+    /** Page file → route. */
+    pages: Map<string, string>;
+    /** Product file → the page it counts under. */
+    owner: Map<string, string>;
+}
+declare function mapRoutes(files: string[]): Routes;
+/** `/(app)/companies/[key]` → `/companies/[key]`; `` → `/`. */
+declare function routeOf(dir: string): string;
+
+/**
+ * Resolve an import to a project file, the way the project's bundler would for
+ * the cases that matter here: relative paths and tsconfig `paths` aliases
+ * (`@/components/button`, `@ds/button`), with or without an extension, or a
+ * folder's index. A package import resolves to nothing: the system is a folder
+ * in the project, and the manifest says which.
+ */
+type Resolver = (moduleName: string, fromFile: string) => string | undefined;
+/** A resolver for files in `root`, returning paths relative to it; cached per import. */
+declare function createResolver(root: string, tsconfig?: string): Resolver;
+
+/**
+ * The one place react-scanner is used, so it can be swapped: it has had no
+ * release since October 2024 and pins TypeScript 5.6 for its parser. Anything
+ * that produces a `RawReport` for a list of files can stand in for it.
+ *
+ * react-scanner is run over every JSX element (no `components` or
+ * `importedFrom` filter), sub-components included, so intrinsic elements
+ * like `<button>` come back too. Its raw report is narrowed to the files asked
+ * for, made relative to the root, and flattened into instances.
+ *
+ * Two of its habits are contained here: it prints "Scanned N files" and
+ * "Failed to parse" to the console, which would corrupt a report written to
+ * stdout, and it throws when a folder has no files.
+ */
+/** react-scanner's raw report: component name → instances, with nested sub-components. */
+interface RawReport {
+    [name: string]: RawReportEntry;
+}
+interface RawReportEntry {
+    instances?: RawInstance[];
+    components?: RawReport;
+}
+interface RawInstance {
+    importInfo?: {
+        imported?: string;
+        local: string;
+        moduleName: string;
+        importType: string;
+    };
+    props: Record<string, unknown>;
+    propsSpread: boolean;
+    location: {
+        file: string;
+        start: {
+            line: number;
+            column: number;
+        };
+    };
+}
+/** One JSX element, flattened out of the raw report. */
+interface Instance {
+    /** As written: `button`, `Button`, `Select.Trigger`. */
+    name: string;
+    file: string;
+    line: number;
+    /** From 1. */
+    column: number;
+    importInfo?: RawInstance["importInfo"];
+    props: Record<string, unknown>;
+    spread: boolean;
+}
+interface ScanResult {
+    report: RawReport;
+    instances: Instance[];
+    /** Files the parser gave up on, relative. */
+    failed: string[];
+}
+/** Scan `files` (relative to `root`) for JSX elements. */
+declare function scanJsx(root: string, files: string[]): Promise<ScanResult>;
+declare function flatten(report: RawReport, prefix?: string): Instance[];
+
+/**
+ * Component use, from react-scanner's instances: which elements are system
+ * components and which are raw elements a system component replaces.
+ *
+ * Which imports are the system comes from the manifest alone: an import that
+ * resolves (relative, or through a tsconfig alias) to a component's source
+ * file is that component; one that resolves to another file in the system
+ * folder, such as a barrel `index.ts`, is matched by export name.
+ */
+
+/** The parts of a components.json entry this reads. Accepts the manifest's schema 1 and `designtools.manifest/1`. */
+interface ManifestComponent {
+    name: string;
+    export: string;
+    source: string;
+    replaces?: string[];
+    variants?: {
+        axes: {
+            name: string;
+            default?: string;
+            options: {
+                name: string;
+            }[];
+        }[];
+    };
+}
+interface ComponentsFile {
+    system: string;
+    components: ManifestComponent[];
+}
+/** A `replaces` entry: `button`, `input[type=checkbox]`, `a[href]`. */
+interface Selector {
+    text: string;
+    tag: string;
+    attrs: {
+        name: string;
+        value?: string;
+    }[];
+}
+declare function parseSelector(text: string): Selector | undefined;
+interface Classified {
+    uses: Map<string, (ComponentUse & {
+        entry: ManifestComponent;
+    })[]>;
+    raw: Map<string, RawElement[]>;
+    /** Selector → components that replace it, most specific selectors first. */
+    replaceable: Map<string, {
+        selector: Selector;
+        components: string[];
+    }>;
+}
+declare function classify(instances: Instance[], manifest: ComponentsFile, resolve: Resolver): Classified;
+
+/**
+ * Overrides: a className on a system component that changes its colour,
+ * spacing or radius. That usually means someone fought the component instead
+ * of picking a variant, or the component is missing one.
+ *
+ * Reads the className react-scanner recorded for each system component use
+ * (the literal classes, including those inside `cn()`), and classifies each
+ * class by its utility, with variants and `!` stripped:
+ *   colour   bg-, text-, border-, ring-, fill- … with a colour value: a token
+ *            colour from tokens.json, a palette step, a Tailwind keyword
+ *            colour, or a bracketed colour
+ *   spacing  p-, m-, gap-, space- in any direction
+ *   radius   rounded, rounded-*
+ * Layout, size and type classes (`w-full`, `flex-1`, `text-sm`) are left
+ * alone. Margins count as spacing: they are often placement, but they are
+ * also how a component's own rhythm gets fought.
+ */
+
+interface OverrideContext {
+    /** Colour names usable as a utility value: `primary`, `primary-subdued`, `canvas-foreground`. */
+    colours: Set<string>;
+    /** Palette families: Tailwind's and the tokens' ramps. */
+    families: string[];
+}
+/** Colour names from tokens.json: every `--color-<name>`. */
+declare function colourContext(tokens: {
+    name: string;
+}[], families: string[]): OverrideContext;
+declare function findOverrides(uses: ComponentUse[], ctx: OverrideContext): Override[];
+declare function overrideKind(cls: string, ctx: OverrideContext): OverrideKind | undefined;
+
+/**
+ * Token discipline: classes that bypass the system's tokens, found by
+ * eslint-plugin-better-tailwindcss's `no-restricted-classes` run through
+ * ESLint's Node API with an in-memory flat config. Nothing of the project's
+ * own ESLint setup is read, and nothing is written.
+ *
+ * The restrictions are generated, not configured:
+ *   palette    a primitive ramp step used as a utility, `bg-blue-500` or
+ *              `text-primary-500`: any `--color-<family>-<step>` in tokens.json,
+ *              and Tailwind's default palette, whose steps a project can
+ *              reach even when it never meant to.
+ *   arbitrary  a value in brackets, `p-[13px]`, `bg-[#fff]`, `[mask-type:alpha]`.
+ *              `[var(--token)]` is a token, so it passes, unless the token is
+ *              a palette step.
+ *
+ * The plugin finds class strings wherever Tailwind classes live: className,
+ * cn(), clsx(), tv(), cva() and the like.
+ */
+
+/** Tailwind v4's default palette families. */
+declare const TAILWIND_FAMILIES: string[];
+/** Utilities that take a colour. */
+declare const COLOUR_UTILITIES: string[];
+interface Restriction {
+    pattern: string;
+    message: string;
+}
+/** The `no-restricted-classes` options for a set of palette families. */
+declare function restrictionsFor(families: string[]): Restriction[];
+/** Ramp families in tokens.json: `--color-primary-500` → `primary`. */
+declare function familiesFromTokens(tokens: {
+    name: string;
+}[]): string[];
+interface DisciplineResult {
+    values: Map<string, OffSystemValue[]>;
+    failed: {
+        file: string;
+        reason: string;
+    }[];
+}
+declare function checkDiscipline(root: string, files: string[], families: string[]): Promise<DisciplineResult>;
+
+export { ADHERENCE_SCHEMA, type AdherenceConfig, type AdherenceReport, type BuiltReport, COLOUR_UTILITIES, CONFIG_FILE, type ComponentUsage, type ComponentUse, type ComponentsFile, type ConfigFlags, type Counts, DEFAULT_EXCLUDE, DEFAULT_INCLUDE, type DisciplineResult, type ElementUsage, type FileEntry, GENERATOR, GENERATOR_NAME, type Instance, type ManifestComponent, type OffSystemKind, type OffSystemValue, type Override, type OverrideContext, type OverrideKind, type PropValue, type RawElement, type RawInstance, type RawReport, type RawReportEntry, type Resolver, type Restriction, type RouteEntry, type ScanResult, type Selector, type SkippedFile, type Summary, TAILWIND_FAMILIES, type Timings, UsageError, VERSION, buildReport, checkDiscipline, classify, colourContext, counts, createResolver, familiesFromTokens, findOverrides, flatten, formatMarkdown, listProductFiles, loadConfig, mapRoutes, overrideKind, parseSelector, restrictionsFor, routeOf, scanJsx, serialise };

package/dist/index.js

@@ -0,0 +1,62 @@
+import {
+  ADHERENCE_SCHEMA,
+  COLOUR_UTILITIES,
+  CONFIG_FILE,
+  DEFAULT_EXCLUDE,
+  DEFAULT_INCLUDE,
+  GENERATOR,
+  GENERATOR_NAME,
+  TAILWIND_FAMILIES,
+  UsageError,
+  VERSION,
+  buildReport,
+  checkDiscipline,
+  classify,
+  colourContext,
+  counts,
+  createResolver,
+  familiesFromTokens,
+  findOverrides,
+  flatten,
+  formatMarkdown,
+  listProductFiles,
+  loadConfig,
+  mapRoutes,
+  overrideKind,
+  parseSelector,
+  restrictionsFor,
+  routeOf,
+  scanJsx,
+  serialise
+} from "./chunk-7FM4ZQLW.js";
+export {
+  ADHERENCE_SCHEMA,
+  COLOUR_UTILITIES,
+  CONFIG_FILE,
+  DEFAULT_EXCLUDE,
+  DEFAULT_INCLUDE,
+  GENERATOR,
+  GENERATOR_NAME,
+  TAILWIND_FAMILIES,
+  UsageError,
+  VERSION,
+  buildReport,
+  checkDiscipline,
+  classify,
+  colourContext,
+  counts,
+  createResolver,
+  familiesFromTokens,
+  findOverrides,
+  flatten,
+  formatMarkdown,
+  listProductFiles,
+  loadConfig,
+  mapRoutes,
+  overrideKind,
+  parseSelector,
+  restrictionsFor,
+  routeOf,
+  scanJsx,
+  serialise
+};