praxis-kit 0.1.0

package/dist/_shared/diagnostics.js

@@ -0,0 +1,360 @@
+//#region ../../lib/diagnostics/src/category.ts
+/** The kind of rule a diagnostic reports. The load-bearing distinction:
+*
+*  - `HTML` / `ARIA` — **spec compliance**. The markup or ARIA usage is invalid
+*    per the HTML standard or the ARIA spec. A fact, not a judgement.
+*  - `Accessibility` — **best-practice guidance**. The usage is spec-valid but
+*    inadvisable (e.g. a placeholder standing in for a label). Advisory.
+*
+*  Keep that split deliberate: a rule belongs in `Accessibility` only when it is
+*  *not* an `HTML`/`ARIA` validity fact. The code ranges mirror it — `ARIA2xxx`
+*  and `HTML3xxx` are validity, `A11Y8xxx` is guidance (see `codes.ts`). */
+let DiagnosticCategory = /* @__PURE__ */ function(DiagnosticCategory) {
+	DiagnosticCategory[DiagnosticCategory["Contract"] = 0] = "Contract";
+	DiagnosticCategory[DiagnosticCategory["HTML"] = 1] = "HTML";
+	DiagnosticCategory[DiagnosticCategory["ARIA"] = 2] = "ARIA";
+	DiagnosticCategory[DiagnosticCategory["Composition"] = 3] = "Composition";
+	DiagnosticCategory[DiagnosticCategory["Rendering"] = 4] = "Rendering";
+	DiagnosticCategory[DiagnosticCategory["Accessibility"] = 5] = "Accessibility";
+	DiagnosticCategory[DiagnosticCategory["Performance"] = 6] = "Performance";
+	DiagnosticCategory[DiagnosticCategory["Internal"] = 7] = "Internal";
+	DiagnosticCategory[DiagnosticCategory["Deprecation"] = 8] = "Deprecation";
+	DiagnosticCategory[DiagnosticCategory["Lint"] = 9] = "Lint";
+	return DiagnosticCategory;
+}({});
+//#endregion
+//#region ../../lib/diagnostics/src/codes.ts
+let DiagnosticCode = /* @__PURE__ */ function(DiagnosticCode) {
+	DiagnosticCode["MissingRequiredChild"] = "COMP1001";
+	DiagnosticCode["InvalidParent"] = "COMP1002";
+	DiagnosticCode["InvalidChild"] = "COMP1003";
+	DiagnosticCode["UnexpectedChild"] = "COMP1004";
+	DiagnosticCode["AmbiguousChild"] = "COMP1005";
+	DiagnosticCode["CardinalityMin"] = "COMP1006";
+	DiagnosticCode["CardinalityMax"] = "COMP1007";
+	DiagnosticCode["PositionViolation"] = "COMP1008";
+	DiagnosticCode["AllowedAsViolation"] = "COMP1009";
+	DiagnosticCode["SlotExclusive"] = "SLOT1001";
+	DiagnosticCode["SlotSingleChild"] = "SLOT1002";
+	DiagnosticCode["SlotDiscardedChildren"] = "SLOT1003";
+	DiagnosticCode["SlotRenderFn"] = "SLOT1004";
+	DiagnosticCode["MissingAriaRelationship"] = "ARIA2001";
+	DiagnosticCode["AriaViolation"] = "ARIA2002";
+	DiagnosticCode["AriaAttributeInvalid"] = "ARIA2003";
+	DiagnosticCode["AriaMissingLiveRegion"] = "ARIA2004";
+	DiagnosticCode["AriaMissingAtomic"] = "ARIA2005";
+	DiagnosticCode["AriaRelevantInvalidToken"] = "ARIA2006";
+	DiagnosticCode["AriaRelevantSuperseded"] = "ARIA2007";
+	DiagnosticCode["AriaInvalidRole"] = "ARIA2008";
+	DiagnosticCode["AriaMissingAccessibleName"] = "ARIA2009";
+	DiagnosticCode["AriaAttributeOnPresentational"] = "ARIA2010";
+	DiagnosticCode["AriaHiddenOnFocusable"] = "ARIA2011";
+	DiagnosticCode["AriaRequiredProperty"] = "ARIA2012";
+	DiagnosticCode["AriaInvalidAttributeValue"] = "ARIA2013";
+	DiagnosticCode["AriaRedundantLevelAttribute"] = "ARIA2014";
+	DiagnosticCode["AriaNameProhibited"] = "ARIA2015";
+	DiagnosticCode["InvalidHeadingHierarchy"] = "HTML3001";
+	DiagnosticCode["HtmlEmptyRole"] = "HTML3002";
+	DiagnosticCode["HtmlImplicitRoleRedundant"] = "HTML3003";
+	DiagnosticCode["HtmlImplicitRoleOverride"] = "HTML3004";
+	DiagnosticCode["HtmlStandaloneRegionOverride"] = "HTML3005";
+	DiagnosticCode["HtmlLandmarkRoleOverride"] = "HTML3006";
+	DiagnosticCode["HtmlInvalidChild"] = "HTML3007";
+	DiagnosticCode["HtmlRoleNotPermitted"] = "HTML3008";
+	DiagnosticCode["HtmlInputUnsupportedType"] = "HTML3101";
+	DiagnosticCode["HtmlInputCheckedIgnoredForType"] = "HTML3102";
+	DiagnosticCode["HtmlInputMultipleIgnoredForType"] = "HTML3103";
+	DiagnosticCode["HtmlInputMaxLengthIgnoredForType"] = "HTML3104";
+	DiagnosticCode["HtmlInputMinLengthIgnoredForType"] = "HTML3105";
+	DiagnosticCode["HtmlInputPatternIgnoredForType"] = "HTML3106";
+	DiagnosticCode["HtmlInputMinIgnoredForType"] = "HTML3107";
+	DiagnosticCode["HtmlInputMaxIgnoredForType"] = "HTML3108";
+	DiagnosticCode["HtmlInputStepIgnoredForType"] = "HTML3109";
+	DiagnosticCode["HtmlInputAcceptIgnoredForType"] = "HTML3110";
+	DiagnosticCode["HtmlInputCaptureIgnoredForType"] = "HTML3111";
+	DiagnosticCode["HtmlInputSizeIgnoredForType"] = "HTML3112";
+	DiagnosticCode["HtmlInputAltIgnoredForType"] = "HTML3113";
+	DiagnosticCode["HtmlInputHeightIgnoredForType"] = "HTML3114";
+	DiagnosticCode["HtmlInputWidthIgnoredForType"] = "HTML3115";
+	DiagnosticCode["HtmlAnchorDangerousHref"] = "HTML3201";
+	DiagnosticCode["A11yInputMissingAccessibleName"] = "A11Y8100";
+	DiagnosticCode["A11yInputPlaceholderNotLabel"] = "A11Y8101";
+	DiagnosticCode["A11yInputPasswordAutocomplete"] = "A11Y8102";
+	DiagnosticCode["A11yInputRequiredReadOnlyConflict"] = "A11Y8103";
+	DiagnosticCode["A11yAnchorRoleButtonWithHref"] = "A11Y8200";
+	DiagnosticCode["A11yAnchorAriaDisabledInert"] = "A11Y8201";
+	DiagnosticCode["InvalidRenderingTarget"] = "RENDER4001";
+	DiagnosticCode["LintDeadCompoundKey"] = "LINT5001";
+	DiagnosticCode["LintDeadCompoundValue"] = "LINT5002";
+	DiagnosticCode["LintDeadCompoundNonLiteral"] = "LINT5003";
+	DiagnosticCode["LintMissingStrict"] = "LINT5004";
+	DiagnosticCode["LintInvalidDefaultKey"] = "LINT5005";
+	DiagnosticCode["LintInvalidDefaultValue"] = "LINT5006";
+	DiagnosticCode["LintInvalidDefaultNonLiteral"] = "LINT5007";
+	DiagnosticCode["LintNegativeMin"] = "LINT5008";
+	DiagnosticCode["LintNegativeMax"] = "LINT5009";
+	DiagnosticCode["LintMaxLessThanMin"] = "LINT5010";
+	DiagnosticCode["LintZeroMax"] = "LINT5011";
+	DiagnosticCode["LintMultipleFirst"] = "LINT5012";
+	DiagnosticCode["LintMultipleLast"] = "LINT5013";
+	DiagnosticCode["LintMinSumExceedsCapacity"] = "LINT5014";
+	DiagnosticCode["LintCardinalityViolation"] = "LINT5015";
+	DiagnosticCode["LintAriaTagOverride"] = "LINT5016";
+	DiagnosticCode["ContractUnknownVariantDim"] = "COMP1010";
+	DiagnosticCode["ContractUnknownVariantValue"] = "COMP1011";
+	DiagnosticCode["ContractUnknownRecipeKey"] = "COMP1012";
+	DiagnosticCode["ContractInvalidVariantValue"] = "COMP1013";
+	DiagnosticCode["TailwindMultipleDisplayProps"] = "CSS6001";
+	DiagnosticCode["TailwindReservedLayoutLiteral"] = "CSS6002";
+	DiagnosticCode["TailwindDeadVariantClass"] = "CSS6003";
+	DiagnosticCode["TailwindLayoutOnVoidTag"] = "CSS6004";
+	DiagnosticCode["PluginInvalidShape"] = "PLUGIN7001";
+	DiagnosticCode["PluginPipelineReturnType"] = "PLUGIN7002";
+	DiagnosticCode["InternalError"] = "INTERNAL9000";
+	return DiagnosticCode;
+}({});
+//#endregion
+//#region ../../lib/diagnostics/src/error.ts
+var PraxisError = class extends Error {
+	diagnostic;
+	constructor(diagnostic) {
+		super(diagnostic.message);
+		this.name = "PraxisError";
+		this.diagnostic = diagnostic;
+	}
+};
+//#endregion
+//#region ../../lib/diagnostics/src/severity.ts
+let Severity = /* @__PURE__ */ function(Severity) {
+	Severity[Severity["Debug"] = 0] = "Debug";
+	Severity[Severity["Info"] = 1] = "Info";
+	Severity[Severity["Warning"] = 2] = "Warning";
+	Severity[Severity["Error"] = 3] = "Error";
+	Severity[Severity["Fatal"] = 4] = "Fatal";
+	return Severity;
+}({});
+function isAtLeast(s, threshold) {
+	return s >= threshold;
+}
+//#endregion
+//#region ../../lib/diagnostics/src/policy.ts
+let Enforcement = /* @__PURE__ */ function(Enforcement) {
+	Enforcement[Enforcement["Ignore"] = 0] = "Ignore";
+	Enforcement[Enforcement["Report"] = 1] = "Report";
+	Enforcement[Enforcement["Throw"] = 2] = "Throw";
+	return Enforcement;
+}({});
+var DefaultPolicy = class {
+	reportThreshold;
+	throwThreshold;
+	constructor({ reportThreshold = 1, throwThreshold = 4 } = {}) {
+		if (throwThreshold < reportThreshold) throw new RangeError(`DefaultPolicy: throwThreshold (${Severity[throwThreshold]}) must be >= reportThreshold (${Severity[reportThreshold]})`);
+		this.reportThreshold = reportThreshold;
+		this.throwThreshold = throwThreshold;
+	}
+	resolve(diagnostic) {
+		if (diagnostic.severity >= this.throwThreshold) return 2;
+		if (diagnostic.severity >= this.reportThreshold) return 1;
+		return 0;
+	}
+};
+//#endregion
+//#region ../../lib/diagnostics/src/diagnostics.ts
+var Diagnostics = class {
+	reporter;
+	policy;
+	/** Cheap gate for callers: `false` means a `Severity.Warning` diagnostic would
+	*  be ignored by the policy, so warning-level validation work (often the
+	*  expensive kind) can be skipped entirely. Precomputed at construction.
+	*
+	*  Scoped to Warning deliberately — it is **not** a general "diagnostics on"
+	*  flag. A policy that ignores Warning but reports Info or throws on Error
+	*  still reads `false` here; check the policy directly for other severities. */
+	warnActive;
+	constructor(reporter, policy = new DefaultPolicy()) {
+		this.reporter = reporter;
+		this.policy = policy;
+		this.warnActive = policy.resolve({ severity: 2 }) !== 0;
+	}
+	report(diagnostic) {
+		const enforcement = this.policy.resolve(diagnostic);
+		if (enforcement === 0) return diagnostic;
+		if (enforcement === 2) throw new PraxisError(diagnostic);
+		this.reporter.report(diagnostic);
+		return diagnostic;
+	}
+	debug(input) {
+		return this.report({
+			...input,
+			severity: 0
+		});
+	}
+	info(input) {
+		return this.report({
+			...input,
+			severity: 1
+		});
+	}
+	warn(input) {
+		return this.report({
+			...input,
+			severity: 2
+		});
+	}
+	error(input) {
+		return this.report({
+			...input,
+			severity: 3
+		});
+	}
+	fatal(input) {
+		return this.report({
+			...input,
+			severity: 4
+		});
+	}
+};
+//#endregion
+//#region ../../lib/foundation/src/type-guards.ts
+function isString(value) {
+	return typeof value === "string";
+}
+function isDefined(value) {
+	return value !== void 0;
+}
+function isUndefined(value) {
+	return value === void 0;
+}
+//#endregion
+//#region ../../lib/diagnostics/src/formatter.ts
+function formatDiagnostic(diagnostic) {
+	const level = Severity[diagnostic.severity];
+	const category = DiagnosticCategory[diagnostic.category];
+	const prefix = isDefined(category) ? `[${category}] ` : "";
+	return `${level} ${diagnostic.code}: ${prefix}${diagnostic.message}`;
+}
+//#endregion
+//#region ../../lib/diagnostics/src/result.ts
+function ok(value) {
+	return {
+		ok: true,
+		value
+	};
+}
+function err(error) {
+	return {
+		ok: false,
+		error
+	};
+}
+//#endregion
+//#region ../../lib/diagnostics/src/async-console-reporter.ts
+/** A console reporter that batches a microtask's worth of diagnostics into one
+*  flush and drops duplicates within that window.
+*
+*  Dedup key is the **formatted string**, on purpose: this reporter's job is
+*  console UX — don't print the same line twice. Two distinct diagnostics that
+*  format identically (same code + message, different file/location) collapse to
+*  one printed line. If you need every distinct diagnostic preserved, use
+*  `CollectingReporter`; this one is not a lossless channel. (A
+*  location-aware key is a possible future refinement if `formatDiagnostic`
+*  stops including enough identity.) */
+var AsyncConsoleReporter = class {
+	pending = /* @__PURE__ */ new Set();
+	scheduled = false;
+	report(diagnostic) {
+		const message = formatDiagnostic(diagnostic);
+		if (this.pending.has(message)) return;
+		this.pending.add(message);
+		if (!this.scheduled) {
+			this.scheduled = true;
+			queueMicrotask(() => {
+				this.scheduled = false;
+				for (const msg of this.pending) console.warn(msg);
+				this.pending.clear();
+			});
+		}
+	}
+	/** Clears pending messages. Exposed for test isolation only. */
+	reset() {
+		this.pending.clear();
+		this.scheduled = false;
+	}
+};
+//#endregion
+//#region ../../lib/diagnostics/src/collecting-reporter.ts
+var CollectingReporter = class {
+	collected = [];
+	report(diagnostic) {
+		this.collected.push(diagnostic);
+	}
+	get diagnostics() {
+		return this.collected;
+	}
+	clear() {
+		this.collected.length = 0;
+	}
+};
+//#endregion
+//#region ../../lib/diagnostics/src/console-reporter.ts
+var ConsoleReporter = class {
+	report(diagnostic) {
+		const message = formatDiagnostic(diagnostic);
+		switch (diagnostic.severity) {
+			case 0:
+				console.debug(message);
+				break;
+			case 1:
+				console.info(message);
+				break;
+			case 2:
+				console.warn(message);
+				break;
+			case 3:
+			case 4: console.error(message);
+		}
+	}
+};
+//#endregion
+//#region ../../lib/diagnostics/src/null-reporter.ts
+const nullReporter = { report() {} };
+//#endregion
+//#region ../../lib/diagnostics/src/presets.ts
+const ignoreAllPolicy = { resolve(_) {
+	return 0;
+} };
+const warnOnlyReporter = { report(diagnostic) {
+	console.warn(formatDiagnostic(diagnostic));
+} };
+/** `'silent'` mode — every diagnostic is ignored. */
+const silentDiagnostics = new Diagnostics(nullReporter, ignoreAllPolicy);
+/** `'warn'` mode — Warning and above print to the console; only `Fatal` throws. */
+const warnDiagnostics = new Diagnostics(warnOnlyReporter, new DefaultPolicy({
+	reportThreshold: 2,
+	throwThreshold: 4
+}));
+/** `'throw'` mode — Warning prints, **`Error` and above throw**. Note this is
+*  "errors throw", not "everything throws"; a Warning is still just logged. */
+const throwDiagnostics = new Diagnostics(new ConsoleReporter(), new DefaultPolicy({
+	reportThreshold: 2,
+	throwThreshold: 3
+}));
+//#endregion
+//#region ../../lib/diagnostics/src/resolve-diagnostics.ts
+const PRESETS_BY_MODE = {
+	warn: warnDiagnostics,
+	throw: throwDiagnostics,
+	silent: silentDiagnostics
+};
+/**
+* Resolves an `enforcement.diagnostics` value — a preset name, a full `Diagnostics`
+* instance, or `undefined` — to a concrete `Diagnostics` instance. Lets authors write
+* `enforcement: { diagnostics: 'warn' }` without importing `Diagnostics` or the presets
+* themselves.
+*/
+function resolveDiagnostics(value, fallback) {
+	if (isUndefined(value)) return fallback;
+	return isString(value) ? PRESETS_BY_MODE[value] : value;
+}
+//#endregion
+export { AsyncConsoleReporter, CollectingReporter, ConsoleReporter, DefaultPolicy, DiagnosticCategory, DiagnosticCode, Diagnostics, Enforcement, PraxisError, Severity, err, formatDiagnostic, isAtLeast, nullReporter, ok, resolveDiagnostics, silentDiagnostics, throwDiagnostics, warnDiagnostics };