@yahoo/uds-create-config 5.61.0 → 5.62.0

package/dist/lint/edits.js

@@ -0,0 +1,121 @@
+import { Settings } from "../entities/system/Settings.js";
+import { styleSetEdits } from "../entities/system/component-style-set.js";
+import "../index.js";
+import { AUTHORING_LINT_GROUPS, AUTHORING_LINT_RULES, ruleSeverity } from "./rules.js";
+//#region src/lint/edits.ts
+/**
+* The lint's settings and fixes as config edits: how loud a rule is, a finding kept on purpose, and
+* the one value a finding suggests, written where the finding's was. Create's Lint page and the
+* sidebars write these; `uds lint` reads the settings they leave.
+*/
+/** The system's `settings.lint.rules`. */
+const lintSeverities = (config) => (config ? Settings.get(config)?.lint?.rules : void 0) ?? {};
+/** The system's `settings.lint.ignore`. */
+const lintIgnores = (config) => (config ? Settings.get(config)?.lint?.ignore : void 0) ?? [];
+const rulesOf = (group) => Object.keys(AUTHORING_LINT_RULES).filter((rule) => AUTHORING_LINT_RULES[rule].group === group);
+/** A group's severity: its rules' when they agree, `mixed` when one is set apart. */
+function groupSeverity(group, severities) {
+	const levels = new Set(rulesOf(group).map((rule) => ruleSeverity(rule, severities)));
+	return levels.size === 1 ? [...levels][0] ?? "warn" : "mixed";
+}
+const defaultOff = (group) => "defaultSeverity" in AUTHORING_LINT_GROUPS[group];
+function settingsUpdate(config, data) {
+	const item = Settings.get(config);
+	return [{
+		kind: Settings.kind,
+		operation: "update",
+		path: item?.path ?? Settings.kind,
+		data
+	}];
+}
+/**
+* The settings edit that sets a rule or a group to `off`, `warn` or `error`: its entry in
+* `settings.lint.rules`, or none where the default already says it.
+*
+* - A rule's own entry wins over its group's, so a rule set to what its group gives it drops its own.
+* - A group sets each rule that has no entry of its own. Setting it also clears its rules' own entries,
+*   so the group's choice is the whole answer, the way a "select all" is.
+* - An experimental group's rules are off until each is named, so that group sets each rule by name.
+*/
+function severityEdits({ config, name, severity }) {
+	const severities = { ...lintSeverities(config) };
+	if (name in AUTHORING_LINT_GROUPS) {
+		const group = name;
+		for (const rule of rulesOf(group)) delete severities[rule];
+		if (defaultOff(group)) {
+			for (const rule of rulesOf(group)) if (severity !== "off") severities[rule] = severity;
+		} else if (severity === "warn") delete severities[group];
+		else severities[group] = severity;
+	} else {
+		const rule = name;
+		delete severities[rule];
+		if (ruleSeverity(rule, severities) !== severity) severities[rule] = severity;
+	}
+	return settingsUpdate(config, { "lint.rules": Object.keys(severities).length > 0 ? severities : null });
+}
+/** A finding's entry in `settings.lint.ignore`: as narrow as the finding says where it is. */
+function ignoreEntry(site, reason) {
+	return {
+		rule: site.rule,
+		...site.component ? { component: site.component } : {},
+		...site.token ? { token: site.token } : {},
+		...site.layer ? { layer: site.layer } : {},
+		...site.prop ? { prop: site.prop } : {},
+		...site.when ? { when: site.when } : {},
+		reason
+	};
+}
+const ignoreUpdate = (config, ignore) => settingsUpdate(config, { "lint.ignore": ignore.length > 0 ? ignore : null });
+/** The settings edit that keeps a finding, with why: `uds lint` and Create both leave it out. */
+function ignoreEdits({ config, site, reason }) {
+	return ignoreUpdate(config, [...lintIgnores(config), ignoreEntry(site, reason)]);
+}
+/** The settings edit that puts an ignored finding back. */
+function restoreEdits({ config, entry }) {
+	return ignoreUpdate(config, lintIgnores(config).filter((one) => JSON.stringify(one) !== JSON.stringify(entry)));
+}
+/** The rules whose suggestion is the value to write, at the rule and layer the finding names. */
+const WRITES_SUGGESTION = new Set([
+	"low-contrast",
+	"literal-matches-token",
+	"near-token",
+	"number-in-brackets"
+]);
+/** The style change a finding's suggestion makes, when it has one answer and is this system's. */
+function changeOf(site) {
+	const { component, suggestion } = site;
+	if (site.source || !WRITES_SUGGESTION.has(site.rule)) return void 0;
+	const at = site.target ?? site;
+	if (!component || !at.layer || !at.prop || suggestion === void 0) return;
+	return {
+		layer: at.layer,
+		prop: at.prop,
+		value: site.rule === "number-in-brackets" ? Number(suggestion) : suggestion,
+		...at.whenProps ? { when: at.whenProps } : {},
+		...at.modifiers ? { modifiers: at.modifiers } : {}
+	};
+}
+/** Whether a finding has one value to write, which {@link fixEdits} writes. */
+const hasFix = (site) => changeOf(site) !== void 0;
+/**
+* The edit that writes the suggestion of each finding that has one, where the finding's value was: in
+* the same rule, layer and modifiers. Each component's changes go through one `styleSetEdits`, so two
+* fixes on the same rule and layer write together rather than the second replacing the first.
+*/
+function fixEdits(sites) {
+	const byComponent = /* @__PURE__ */ new Map();
+	for (const site of sites) {
+		const change = changeOf(site);
+		if (!change || !site.component) continue;
+		const changes = byComponent.get(site.component) ?? [];
+		changes.push(change);
+		byComponent.set(site.component, changes);
+	}
+	return [...byComponent].flatMap(([path, changes]) => styleSetEdits({
+		path,
+		changes,
+		isInteraction: () => false
+	}));
+}
+//#endregion
+export { fixEdits, groupSeverity, hasFix, ignoreEdits, ignoreEntry, lintIgnores, lintSeverities, restoreEdits, rulesOf, severityEdits };

package/dist/lint/index.d.ts

@@ -0,0 +1,5 @@
+import { AUTHORING_LINT_GROUPS, AUTHORING_LINT_RULES, AuthoringLintFix, AuthoringLintGroup, AuthoringLintRule, AuthoringLintSeverity, CONFIG_LINT_RULES, ConfigLintCheck, ConfigReadLintRule, LintReads, lintReads, ruleSeverity } from "./rules.js";
+import { ConfigLintFinding, ConfigLintOptions, LintIgnore, ignoredBy } from "./context.js";
+import { LintFixSite, fixEdits, groupSeverity, hasFix, ignoreEdits, ignoreEntry, lintIgnores, lintSeverities, restoreEdits, rulesOf, severityEdits } from "./edits.js";
+import { AuthoringLintEdit, AuthoringLintFinding, AuthoringLintResult, LintIgnoreProblem, LintRun, LintSources, lint, lintConfig } from "./lint.js";
+export { AUTHORING_LINT_GROUPS, AUTHORING_LINT_RULES, AuthoringLintEdit, AuthoringLintFinding, AuthoringLintFix, AuthoringLintGroup, AuthoringLintResult, AuthoringLintRule, AuthoringLintSeverity, CONFIG_LINT_RULES, ConfigLintCheck, type ConfigLintFinding, type ConfigLintOptions, ConfigReadLintRule, LintFixSite, type LintIgnore, LintIgnoreProblem, LintReads, LintRun, LintSources, fixEdits, groupSeverity, hasFix, ignoreEdits, ignoreEntry, ignoredBy, lint, lintConfig, lintIgnores, lintReads, lintSeverities, restoreEdits, ruleSeverity, rulesOf, severityEdits };

package/dist/lint/index.js

@@ -0,0 +1,5 @@
+import { ignoredBy } from "./context.js";
+import { AUTHORING_LINT_GROUPS, AUTHORING_LINT_RULES, CONFIG_LINT_RULES, lintReads, ruleSeverity } from "./rules.js";
+import { fixEdits, groupSeverity, hasFix, ignoreEdits, ignoreEntry, lintIgnores, lintSeverities, restoreEdits, rulesOf, severityEdits } from "./edits.js";
+import { lint, lintConfig } from "./lint.js";
+export { AUTHORING_LINT_GROUPS, AUTHORING_LINT_RULES, CONFIG_LINT_RULES, fixEdits, groupSeverity, hasFix, ignoreEdits, ignoreEntry, ignoredBy, lint, lintConfig, lintIgnores, lintReads, lintSeverities, restoreEdits, ruleSeverity, rulesOf, severityEdits };

package/dist/lint/lint.d.ts

@@ -0,0 +1,107 @@
+import { Config } from "../framework/Config.js";
+import { AuthoringLintFix, AuthoringLintRule, AuthoringLintSeverity } from "./rules.js";
+import { ConfigLintFinding, ConfigLintOptions } from "./context.js";
+
+//#region src/lint/lint.d.ts
+/** One text replacement an `auto` fix makes: `text` in place of `[start, end)` in `file`. */
+interface AuthoringLintEdit {
+  /** Absolute. */
+  readonly file: string;
+  readonly start: number;
+  readonly end: number;
+  readonly text: string;
+}
+/** A finding at a line of the sources. */
+interface AuthoringLintFinding {
+  readonly rule: AuthoringLintRule;
+  readonly severity: Exclude<AuthoringLintSeverity, 'off'>;
+  /** The component whose declaration holds the site, or the file's helper name outside one. */
+  readonly owner: string;
+  /** Relative to the config's directory. */
+  readonly file: string;
+  /** 1-based. */
+  readonly line: number;
+  /** 1-based. */
+  readonly column: number;
+  /** The site as written, on one line, cut short past 80 characters. */
+  readonly snippet: string;
+  /** What this site in particular does, beyond the rule's own description. */
+  readonly detail?: string;
+  /** How it gets fixed. */
+  readonly fix: AuthoringLintFix;
+  /** The edits that make the fix: `uds lint --fix` makes them for an `auto` fix, and for any other
+   *  they're what a person or an agent would write, to check first. */
+  readonly edits?: readonly AuthoringLintEdit[];
+  /**
+   * The linked system the site changes something of, by its slug. What a system adds over another's
+   * may belong in that system instead, where every system linking it would get it, so a finding says
+   * whose it is: the change can be proposed there, or made there by its owners.
+   */
+  readonly upstream?: string;
+  /** Where {@link upstream} is: a sibling in this repo, which the change can be made in, or a copy
+   *  installed from its publisher, which the next install overwrites. Relative to the config's
+   *  directory. */
+  readonly upstreamAt?: {
+    readonly local: boolean;
+    readonly path: string;
+  };
+}
+interface AuthoringLintResult {
+  readonly findings: AuthoringLintFinding[];
+  /** Names in `settings.lint.rules` that are no rule and no group, which set nothing. */
+  readonly unknownRules: string[];
+  /** `uds-lint-ignore` comments that quiet nothing: one with no reason, one naming no rule, or one
+   *  with no finding of its rule on its line or the line below. */
+  readonly ignores: LintIgnoreProblem[];
+}
+interface LintIgnoreProblem {
+  /** Relative to the config's directory. */
+  readonly file: string;
+  /** 1-based. */
+  readonly line: number;
+  readonly rule: string;
+  readonly problem: 'malformed' | 'no-reason' | 'unknown-rule' | 'unused';
+}
+/**
+ * Where the rules that read the sources run. The config says what each rule is and checks the ones
+ * that read it; an adapter reads the source files: codegen's from disk for `uds lint`, Create's
+ * server from a branch's sealed sources.
+ */
+interface LintSources {
+  /**
+   * The config as its renders say, for the config's checks: each component's layer tree and the
+   * props its render reads, which a build reads off the sources. An adapter whose config already
+   * carries them (a built system's) leaves this out.
+   */
+  prepare?(config: Config): Config | Promise<Config>;
+  /**
+   * Runs the rules that read the sources over `config`'s system, and reports each of
+   * `configFindings` at the line that writes it.
+   */
+  lint(input: {
+    readonly config: Config;
+    readonly configFindings: readonly ConfigLintFinding[];
+  }): AuthoringLintResult | Promise<AuthoringLintResult>;
+}
+/** The rules that read the config, synchronously: what Create runs in the browser on every edit. */
+declare function lintConfig(config: Config, options?: ConfigLintOptions): ConfigLintFinding[];
+/** What {@link lint} found. */
+interface LintRun {
+  /** The config's findings, with what `settings.lint.ignore` keeps left out. With sources, these are
+   *  in {@link sources} too, at their lines. */
+  readonly config: readonly ConfigLintFinding[];
+  /** What the sources found, when an adapter ran them. */
+  readonly sources?: AuthoringLintResult;
+}
+/**
+ * Every rule over `config`: the config's checks here, and the rules that read the sources through
+ * `sources`. Without an adapter the source rules don't run, and the rules that read both are checked
+ * on the config instead.
+ */
+declare function lint(config: Config, {
+  sources
+}?: {
+  sources?: LintSources;
+}): Promise<LintRun>;
+//#endregion
+export { AuthoringLintEdit, AuthoringLintFinding, AuthoringLintResult, LintIgnoreProblem, LintRun, LintSources, lint, lintConfig };

package/dist/lint/lint.js

@@ -0,0 +1,91 @@
+import { Settings } from "../entities/system/Settings.js";
+import "../index.js";
+import { configLintContext, ignoredBy } from "./context.js";
+import { AUTHORING_LINT_RULES, lintReads } from "./rules.js";
+//#region src/lint/lint.ts
+/**
+* Running the lint. `lintConfig` runs the rules that read the config, synchronously, wherever a config
+* is loaded. `lint` runs every rule: the config's own, and the ones that read the sources through a
+* {@link LintSources} adapter when one is given.
+*/
+/** The rules that read the config alone; one that reads both is left to the sources when they run. */
+const READS_CONFIG_ONLY = Object.keys(AUTHORING_LINT_RULES).filter((rule) => lintReads(rule) === "config");
+/** The rules that read the config, synchronously: what Create runs in the browser on every edit. */
+function lintConfig(config, options = {}) {
+	const rules = options.rules ?? READS_CONFIG_ONLY;
+	const ctx = configLintContext({
+		config,
+		rules: new Set(rules),
+		...options.own ? { own: options.own } : {}
+	});
+	const checks = rules.map((rule) => ({
+		rule,
+		check: AUTHORING_LINT_RULES[rule].check
+	}));
+	const findings = [];
+	const seen = /* @__PURE__ */ new Set();
+	const reporter = (rule) => ({ at, fixAt, token, prop, value, ...rest }) => {
+		const finding = {
+			rule,
+			...at ? ctx.at(at.component.path, at.site) : {},
+			...token !== void 0 ? { token } : {},
+			...prop !== void 0 ? { prop } : {},
+			...value !== void 0 ? { value } : {},
+			...rest,
+			...fixAt ? { target: ctx.at(fixAt.component.path, fixAt.site) } : {}
+		};
+		const key = JSON.stringify([
+			finding.rule,
+			finding.component,
+			finding.token,
+			finding.when,
+			finding.layer,
+			finding.prop,
+			finding.modifiers
+		]);
+		if (seen.has(key)) return;
+		seen.add(key);
+		findings.push(finding);
+	};
+	const at = (scope) => checks.flatMap(({ rule, check }) => {
+		const run = check[scope];
+		return run ? [{
+			run,
+			report: reporter(rule)
+		}] : [];
+	});
+	const byValue = at("value");
+	const byLayer = at("layer");
+	const byComponent = at("component");
+	const bySystem = at("system");
+	for (const component of ctx.components) {
+		if (byValue.length > 0) for (const site of component.sites) {
+			if (typeof site.value !== "string" && typeof site.value !== "number") continue;
+			const value = ctx.value(component, site);
+			for (const { run, report } of byValue) run(ctx, value, report);
+		}
+		if (byLayer.length > 0) for (const layer of ctx.layers(component)) for (const { run, report } of byLayer) run(ctx, layer, report);
+		for (const { run, report } of byComponent) run(ctx, component, report);
+	}
+	for (const { run, report } of bySystem) run(ctx, report);
+	return findings;
+}
+/**
+* Every rule over `config`: the config's checks here, and the rules that read the sources through
+* `sources`. Without an adapter the source rules don't run, and the rules that read both are checked
+* on the config instead.
+*/
+async function lint(config, { sources } = {}) {
+	const ignores = Settings.get(config)?.lint?.ignore ?? [];
+	const found = lintConfig(sources?.prepare ? await sources.prepare(config) : config, sources ? {} : { rules: Object.keys(AUTHORING_LINT_RULES).filter((rule) => lintReads(rule) !== "code") }).filter((finding) => !ignoredBy(ignores, finding));
+	if (!sources) return { config: found };
+	return {
+		config: found,
+		sources: await sources.lint({
+			config,
+			configFindings: found
+		})
+	};
+}
+//#endregion
+export { lint, lintConfig };