@fusion.dev/helix-diagnostics 0.140.0 → 0.142.0

package/README.md

@@ -126,6 +126,54 @@ The address is always on a local host.
   `[::1]`, `*.localhost`, and `*.test`. It listens on `127.0.0.1`, so nothing
   else on your network reaches it, and production pages never send to it.
 
+## Scan your code
+
+`helix scan` reads every stylesheet, template, and module in your repository,
+judges them against the lint data of the Helix packages you installed, and
+writes one run in the shape a page writes, with `source: "code"`:
+
+```sh
+npx helix scan
+npx helix scan --build dist --out reports/helix-diagnostics.json
+```
+
+- **Each finding has its file and line**, and the kind and fingerprint a page
+  gives the same fault, so a dashboard joins the two.
+- **It reads every file, and so every route.** A page sees the routes someone
+  opened, so a scan is the better count of what your project uses. An element
+  written once counts once, however many times it renders, and
+  `usage.counted` is `scanned`.
+- **What only a page can settle is `unsettled`.** A hook set on a Helix tag
+  that does not have it works where an element with the hook is inside that
+  tag, and only the running page shows whether one is. The scan lists these
+  apart, each with the fingerprint the page's finding would have, and they
+  never fail the scan.
+- **It reads** CSS, Sass, and Less files; HTML, Vue, Svelte, and Astro
+  templates; MDX outside its code samples; and JavaScript and TypeScript, for
+  JSX, Lit's `html` and `css` templates, and Angular's inline templates. A
+  file that does not parse, and a stylesheet in Sass's indented syntax or
+  Stylus, is listed in `coverage.unreadable`.
+- **It leaves out** what `.gitignore` leaves out, the folders a build or a
+  package manager writes, and tests: a name with `.test.` or `.spec.`, and
+  anything under `__tests__`.
+- **An attribute is checked where the code writes it as one.** In
+  `tone="primary"`, the name and the value are checked. Lit's `tone=${...}`
+  writes the attribute, so its name is checked. An expression in JSX, Svelte,
+  or Angular, and Vue's `:tone`, set a property where the element has one, so
+  none of them is checked.
+- **With `--build`, it weighs your bundle**: what each Helix family and
+  package adds to it, from its source maps, as `performance.weight`. Turn
+  source maps on in your bundler, and pass the folder it writes the browser's
+  files to, such as `dist` or `.next/static`.
+- **With `--out`, it writes its run to the CI file**, and keeps the runs
+  `helix diagnostics` wrote there. The relay keeps the scan's run the same
+  way, so the two share one file, in either order.
+
+It reads `helix-diagnostics.json` from the project, then from the directory it
+runs in, or the file `--config <path>` names, and refuses a setting that names
+nothing, as the page does. It exits 1 on a finding at `error`, and 3 where the
+project installs no Helix lint data. `--json` prints the run.
+
 ## Run it once, directly
 
 `diagnose()` is one run, which `initDiagnostics()` makes for you. Call it
@@ -169,9 +217,12 @@ A report is one run, in one shape for every sink, versioned by `schema`:
   severity, the tag and its family, a `category` (`styling`, `markup`,
   `integrity`, or `guideline`), an `owner` (`consumer`, or `helix` for a fault
   in the library), a `fingerprint` that stays the same from one run to the next
-  for the same fault, and the rule's own text as evidence.
+  for the same fault, and the rule's own text as evidence. A scan's findings
+  also have the file's `line`.
 - **`performance`**: what the components cost, by tag, where you asked for it.
   See [Performance](#performance).
+- **`unsettled`**: from a scan, the faults only a page can settle. See
+  [Scan your code](#scan-your-code).
 - **`runtime`**: what the library reported going wrong as it ran on the page,
   from its first load. One entry per distinct event, with its `kind`, its
   `tag`, the sentence that says what to do, how many times it was reported,
@@ -284,6 +335,9 @@ that has not asked pays one property read per element. Layout shift and long
 tasks are measured in Chromium only. Elsewhere `measured` says so, and their
 numbers are left out.
 
+What each family adds to your bundle is measured from the code, by
+`helix scan --build`, as `weight`. See [Scan your code](#scan-your-code).
+
 ## Configure it
 
 Every setting can be given in three places, and a later place wins, field by
@@ -357,6 +411,10 @@ A fault found on many pages is one line, with the pages it was on. `error`
 findings fail the job by default; pass `failOn: 'warn'` to fail on warnings
 too, or `'never'` to report without failing.
 
+`ciSink` writes the whole file, so to add a run from your code, run
+`helix scan --out` with the same file after it. The scan keeps the runs it
+finds there.
+
 ## Versions
 
 `@fusion.dev/helix-core` lists its version on the page as it loads, and every

package/dist/index.d.ts

@@ -35,7 +35,7 @@ export { fingerprintOf, normalize } from './identity.js';
 export { type Diagnostics, INSTANCE, type InitOptions, initDiagnostics } from './init.js';
 export type { LintData, LintTag, ManifestSource, Published, Tier } from './manifest.js';
 export { index, lintOf, nearest } from './manifest.js';
-export type { Category, Configuration, Coverage, Environment, Finding, FindingCategory, Kind, Layer, Origin, Owner, Report, Severity, Unreadable, Usage, } from './report.js';
+export type { Category, Configuration, Coverage, Environment, Finding, FindingCategory, Kind, Layer, Origin, Owner, Report, Severity, Unreadable, Usage, Weight, } from './report.js';
 export { CATEGORIES, KINDS } from './report.js';
 export { type Override, type Rules, SHIPPED_RULES } from './rules.js';
 export { TIMING, type Timing } from './schedule.js';

package/dist/report.d.ts

@@ -13,9 +13,10 @@
 /** Where a rule was read from, so a reader can go and look at it. */
 export interface Origin {
     /**
-     * The rule's own text, which is the receipt.
+     * The rule's own text, which is the receipt. For a scan's finding about
+     * an attribute, the opening tag's text.
      *
-     * **There is no line number and there cannot be one.** CSSOM exposes
+     * **A page has no line number and cannot have one.** CSSOM exposes
      * `cssText` and an index within the sheet; the byte offset in the authored
      * file is not in the object model at any level. A line was asked for, and
      * this is the honest substitute: the text of the rule is what a
@@ -23,9 +24,18 @@ export interface Origin {
      * line number would not.
      */
     cssText: string;
-    /** Position within the sheet's own rule list, for a sheet with repeats. */
+    /**
+     * Position within the sheet's own rule list, for a sheet with repeats. For
+     * a scan's finding about an attribute, the element's position in the file.
+     */
     index: number;
-    /** The sheet's `href`, or a description of why it has none. */
+    /**
+     * The line the rule's first declaration, or the element's opening tag, is
+     * on, counting from 1. A scan reads the file, so its findings have one. A
+     * page's never do.
+     */
+    line?: number;
+    /** The sheet's `href`, or a description of why it has none. For a scan, the file's path. */
     sheet: string;
 }
 /**
@@ -109,6 +119,23 @@ export type Identified = Omit<Finding, 'decidedBy' | 'severity'>;
 export declare const CATEGORIES: readonly ['assist', 'configuration', 'coverage', 'findings', 'performance', 'runtime', 'usage'];
 /** A kind of telemetry. */
 export type Category = (typeof CATEGORIES)[number];
+/**
+ * What each Helix family adds to a build, measured by `helix scan --build`
+ * from the build's source maps, in bytes before compression.
+ */
+export interface Weight {
+    /** The bytes from each family's folder, across the tiers. */
+    families: Record<string, number>;
+    /** The bundle files read with a source map, and without one, which cannot be split. */
+    files: {
+        mapped: number;
+        unmapped: number;
+    };
+    /** The bytes from each Helix package. */
+    packages: Record<string, number>;
+    /** Every byte in the bundle files read, Helix or not. */
+    total: number;
+}
 /**
  * What the components cost on a page, by tag, where a project asked for it.
  */
@@ -140,6 +167,12 @@ export interface PerformanceReport {
         /** The layout shift its elements moved, summed as the browser scores it. */
         shift: number;
     }>;
+    /**
+     * What each family adds to the build, from a scan given the build. A scan
+     * measures nothing in a browser, so its `measured` is false and its `tags`
+     * are empty.
+     */
+    weight?: Weight;
 }
 /**
  * A runtime event as a run holds it: what `@fusion.dev/helix-core` reported
@@ -168,9 +201,14 @@ export interface RuntimeEntry {
 }
 /** Where a run was declared to happen. Undeclared is never sent. */
 export type Environment = 'ci' | 'development' | 'production';
-/** A sheet the collector could not read, and the reason. */
+/**
+ * A sheet the collector could not read, and the reason. For a scan, a file
+ * that did not parse is `threw`, and a stylesheet in a language the scan does
+ * not read, such as Sass's indented syntax or Stylus, is `unsupported`.
+ */
 export interface Unreadable {
-    reason: 'cross-origin' | 'detached' | 'threw';
+    reason: 'cross-origin' | 'detached' | 'threw' | 'unsupported';
+    /** The sheet's `href`, or for a scan, the file's path. */
     sheet: string;
 }
 /**
@@ -183,6 +221,8 @@ export interface Unreadable {
  * hole this reports rather than steps over.
  */
 export interface Coverage {
+    /** Files read, for a scan: stylesheets, templates, and modules. */
+    files?: number;
     /** Sheets whose rules were read end to end. */
     read: number;
     /** Shadow roots entered, including nested ones. */
@@ -214,9 +254,10 @@ export interface Usage {
      * How the elements were counted. `watched`: every element that rendered
      * since `watch()` began, including the ones that have gone, such as a
      * closed dialog. `walked`: the elements in the page at the moment of the
-     * run, which misses those.
+     * run, which misses those. `scanned`: each element written in the code, by
+     * `helix scan`, counted once however many times it renders.
      */
-    counted: 'walked' | 'watched';
+    counted: 'scanned' | 'walked' | 'watched';
     /** Each hook the page's stylesheets set, by tag, counted per declaration. */
     hooks: Record<string, Record<string, number>>;
     /**
@@ -321,6 +362,12 @@ export interface Report {
      * first load: one entry per distinct event, counted.
      */
     runtime: RuntimeEntry[];
+    /**
+     * The faults a scan found and only a page can settle, such as a hook set
+     * on an element for one inside it, each with the fingerprint the page's
+     * finding would have. A scan's alone.
+     */
+    unsettled?: Identified[];
     /**
      * The project's own name and labels, as its configuration gives them. The
      * key is never written into a report.

package/dist/version.d.ts

@@ -6,4 +6,4 @@
  * release, so the two never disagree; a spec beside this holds them to it.
  * Nothing else in the running code knows which release it is.
  */
-export declare const VERSION = "0.140.0";
+export declare const VERSION = "0.142.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '0.140.0';
+export const VERSION = '0.142.0';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-diagnostics",
   "description": "Finds the Helix mistakes that are valid CSS: dead parts, misnamed hooks, two copies of the library.",
-  "version": "0.140.0",
+  "version": "0.142.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -33,7 +33,7 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "devDependencies": {
-    "@fusion.dev/helix-testing": "0.140.0",
+    "@fusion.dev/helix-testing": "0.142.0",
     "@types/bun": "^1.3.0"
   },
   "homepage": "https://fusion.dev",