@shivaedev/quality 0.0.0 → 0.1.0

package/src/report/render.ts

@@ -0,0 +1,85 @@
+import { describeEntry, describeTally, type Regression } from "../baseline/compare.ts";
+import { type Outcome, passes } from "../engine/evaluate.ts";
+import { groupBy, keyOf, type Violation } from "../engine/violation.ts";
+import { plural } from "./plural.ts";
+import { staleSections } from "./stale.ts";
+
+export type WarningDetail = "summary" | "all";
+
+export interface ReportContext {
+	readonly descriptions: ReadonlyMap<string, string>;
+	readonly registry: string;
+	readonly baseline: string;
+	readonly checked: number;
+	readonly warnings: WarningDetail;
+}
+
+const LISTED_FILES = 5;
+
+const locate = (violation: Violation): string => (violation.line === undefined ? violation.file : `${violation.file}:${violation.line}`);
+
+const regressionNote = (regression: Regression): string =>
+	`  ${regression.entry.file} is over its baseline: ${describeTally(regression.tally)} against ${describeEntry(regression.entry)} baselined.`;
+
+const heading = (label: string, rule: string, violations: ReadonlyArray<Violation>, context: ReportContext): ReadonlyArray<string> => {
+	const description = context.descriptions.get(rule);
+	return [`${label} ${rule} (${violations.length})`, ...(description === undefined ? [] : [`  ${description}`])];
+};
+
+const detailed = (violations: ReadonlyArray<Violation>, regressions: ReadonlyMap<string, Regression>): ReadonlyArray<string> =>
+	[...groupBy(violations, (violation) => violation.file).values()].flatMap((inFile) => {
+		const first = inFile[0];
+		const regression = first === undefined ? undefined : regressions.get(keyOf(first.rule, first.file));
+		return [
+			...inFile.map((violation) => `  ${locate(violation)}  ${violation.message}`),
+			...(regression === undefined ? [] : [regressionNote(regression)]),
+		];
+	});
+
+const summarized = (violations: ReadonlyArray<Violation>): ReadonlyArray<string> => {
+	const files = [...groupBy(violations, (violation) => violation.file).entries()].sort(([, left], [, right]) => right.length - left.length);
+	const listed = files.slice(0, LISTED_FILES).map(([file, inFile]) => `${file} (${inFile.length})`);
+	const rest = files.length - listed.length;
+	return [`  ${listed.join(", ")}${rest > 0 ? `, and ${plural(rest, "more file", "more files")}` : ""}. --warnings all lists each one.`];
+};
+
+const ruleSections = (
+	label: string,
+	violations: ReadonlyArray<Violation>,
+	context: ReportContext,
+	body: (inRule: ReadonlyArray<Violation>) => ReadonlyArray<string>,
+): ReadonlyArray<string> =>
+	[...groupBy(violations, (violation) => violation.rule).entries()].map(([rule, inRule]) =>
+		[...heading(label, rule, inRule, context), ...body(inRule)].join("\n"),
+	);
+
+const failures = (outcome: Outcome): string => {
+	const stale = outcome.staleBaseline.length + outcome.staleRegistry.length;
+	return [
+		...(outcome.errors.length > 0 ? [plural(outcome.errors.length, "error")] : []),
+		...(stale > 0 ? [plural(stale, "stale entry", "stale entries")] : []),
+	].join(" and ");
+};
+
+const summary = (outcome: Outcome, context: ReportContext): string => {
+	const verdict = passes(outcome) ? "quality: passed" : `quality: failed with ${failures(outcome)}`;
+	const warnings = outcome.warnings.length > 0 ? `; ${plural(outcome.warnings.length, "warning")} from rules still at warn` : "";
+	const hidden = [
+		...(outcome.baselined > 0 ? [`${outcome.baselined} baselined`] : []),
+		...(outcome.registered > 0 ? [`${outcome.registered} registered`] : []),
+	];
+	const suppressed =
+		hidden.length === 0 ? "" : `; ${hidden.join(" and ")} ${outcome.baselined + outcome.registered === 1 ? "violation" : "violations"} not shown`;
+	return `${verdict}${warnings}. ${plural(context.checked, "source file")} checked${suppressed}.`;
+};
+
+export const render = (outcome: Outcome, context: ReportContext): string => {
+	const regressions = new Map(outcome.regressions.map((regression) => [keyOf(regression.entry.rule, regression.entry.file), regression]));
+	const warningBody = context.warnings === "all" ? (inRule: ReadonlyArray<Violation>) => detailed(inRule, regressions) : summarized;
+	return [
+		...ruleSections("error", outcome.errors, context, (inRule) => detailed(inRule, regressions)),
+		...ruleSections("warn", outcome.warnings, context, warningBody),
+		...staleSections(outcome, context),
+		summary(outcome, context),
+	].join("\n\n");
+};

package/src/report/stale.ts

@@ -0,0 +1,30 @@
+import type { StaleBaselineEntry } from "../baseline/compare.ts";
+import type { Outcome } from "../engine/evaluate.ts";
+import type { StaleRegistryEntry } from "../exceptions/registry.ts";
+import { plural } from "./plural.ts";
+
+interface StaleFiles {
+	readonly registry: string;
+	readonly baseline: string;
+}
+
+const section = (file: string, guidance: string, lines: ReadonlyArray<string>): ReadonlyArray<string> =>
+	lines.length === 0 ? [] : [[`error ${file}: ${plural(lines.length, "stale entry", "stale entries")}`, `  ${guidance}`, ...lines].join("\n")];
+
+const baselineLine = ({ entry, problem }: StaleBaselineEntry): string => `  ${entry.rule} ${entry.file} ${problem}.`;
+
+const registryLine = ({ entry, problem }: StaleRegistryEntry): string =>
+	`  ${entry.rule} ${entry.file}${entry.subject === undefined ? "" : ` (${entry.subject})`} ${problem}.`;
+
+export const staleSections = (outcome: Outcome, files: StaleFiles): ReadonlyArray<string> => [
+	...section(
+		files.baseline,
+		"The baseline only shrinks. Run `quality baseline prune` to drop fixed debt; prune never adds or raises an entry.",
+		outcome.staleBaseline.map(baselineLine),
+	),
+	...section(
+		files.registry,
+		"Every registered exception must still apply. Remove the entries whose exception is gone.",
+		outcome.staleRegistry.map(registryLine),
+	),
+];

package/src/rule.ts

@@ -0,0 +1,90 @@
+import { describeIssue, type StandardSchemaV1 } from "./standard-schema.ts";
+
+export interface Finding {
+	readonly file: string;
+	readonly line?: number | undefined;
+	readonly message: string;
+	/** Tells apart exceptions of one rule in one file, such as which Biome rule an override turns off. */
+	readonly subject?: string | undefined;
+	/** A size where larger is worse, such as a file's line count. A baselined file may not grow past it. */
+	readonly measure?: number | undefined;
+}
+
+export type Findings = ReadonlyArray<Finding>;
+
+export interface SourceFile {
+	readonly path: string;
+	readonly text: string;
+	readonly lines: ReadonlyArray<string>;
+}
+
+export interface RuleInputs {
+	readonly root: string;
+	readonly files: ReadonlyArray<string>;
+	readonly sources: ReadonlyArray<SourceFile>;
+	readonly readText: (path: string) => Promise<string | undefined>;
+}
+
+export interface RuleContext<Options> extends RuleInputs {
+	readonly options: Options;
+}
+
+export type Configured =
+	| { readonly _tag: "Invalid"; readonly issues: ReadonlyArray<string> }
+	| { readonly _tag: "Ready"; readonly check: (inputs: RuleInputs) => Promise<Findings> };
+
+export interface Rule<Id extends string = string, Input = unknown> {
+	readonly id: Id;
+	readonly description: string;
+	// Method syntax keeps rules with different options in one list; configure validates its input at runtime.
+	configure(options: Input | undefined): Promise<Configured>;
+}
+
+interface RuleDefinition<Id extends string, Options> {
+	readonly id: Id;
+	readonly description: string;
+	readonly check: (context: RuleContext<Options>) => Findings | PromiseLike<Findings>;
+}
+
+interface RuleDefinitionWithOptions<Id extends string, Input, Options> extends RuleDefinition<Id, Options> {
+	readonly options: StandardSchemaV1<Input, Options>;
+}
+
+interface RuleDefinitionWithoutOptions<Id extends string> extends RuleDefinition<Id, undefined> {
+	readonly options?: undefined;
+}
+
+const noOptions: StandardSchemaV1<undefined, undefined> = {
+	"~standard": {
+		validate: (value) => (value === undefined ? { value: undefined } : { issues: [{ message: "this rule takes no options" }] }),
+		vendor: "@shivaedev/quality",
+		version: 1,
+	},
+};
+
+const configureWith =
+	<Input, Options>(schema: StandardSchemaV1<Input, Options>, check: RuleDefinition<string, Options>["check"], absent: unknown) =>
+	async (options: unknown): Promise<Configured> => {
+		const result = await schema["~standard"].validate(options ?? absent);
+		if (result.issues !== undefined) {
+			return { _tag: "Invalid", issues: result.issues.map(describeIssue) };
+		}
+		const value = result.value;
+		return { _tag: "Ready", check: async (inputs) => check({ ...inputs, options: value }) };
+	};
+
+/**
+ * Defines a rule. Options are an object validated by a Standard Schema; a rule the config gives no options validates `{}`,
+ * so give each option a default or make it optional.
+ */
+export function defineRule<const Id extends string, Input, Options>(definition: RuleDefinitionWithOptions<Id, Input, Options>): Rule<Id, Input>;
+export function defineRule<const Id extends string>(definition: RuleDefinitionWithoutOptions<Id>): Rule<Id, undefined>;
+export function defineRule<const Id extends string, Input, Options>(
+	definition: RuleDefinitionWithOptions<Id, Input, Options> | RuleDefinitionWithoutOptions<Id>,
+): Rule<Id, Input> | Rule<Id, undefined> {
+	const configure =
+		definition.options === undefined
+			? configureWith(noOptions, definition.check, undefined)
+			: configureWith(definition.options, definition.check, {});
+	return { configure, description: definition.description, id: definition.id };
+}

package/src/rules/built-in.ts

@@ -0,0 +1,3 @@
+import { maxLines } from "./max-lines.ts";
+
+export const builtInRules = [maxLines] as const;

package/src/rules/max-lines.ts

@@ -0,0 +1,31 @@
+import { Effect, Schema } from "effect";
+import ignore from "ignore";
+import { defineRule, type Finding, type SourceFile } from "../rule.ts";
+
+const DEFAULT_TEST_FILES: ReadonlyArray<string> = ["*.test.*", "*.spec.*", "test/", "tests/", "__tests__/"];
+const DECLARATION = /\.d\.[cm]?ts$/;
+
+const Limit = Schema.Int.check(Schema.isGreaterThan(0));
+
+const MaxLinesOptions = Schema.Struct({
+	source: Limit.pipe(Schema.withDecodingDefaultKey(Effect.succeed(150))),
+	test: Limit.pipe(Schema.withDecodingDefaultKey(Effect.succeed(300))),
+	testFiles: Schema.Array(Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed(DEFAULT_TEST_FILES))),
+});
+
+const oversized = (file: SourceFile, limit: number): ReadonlyArray<Finding> =>
+	file.lines.length <= limit
+		? []
+		: [{ file: file.path, measure: file.lines.length, message: `${file.lines.length} lines exceeds the ${limit}-line limit.` }];
+
+export const maxLines = defineRule({
+	id: "structure/max-lines",
+	description: "Keep each module to one job. Split a long file along its responsibilities; never golf it under the limit.",
+	options: Schema.toStandardSchemaV1(MaxLinesOptions, { parseOptions: { errors: "all", onExcessProperty: "error" } }),
+	check: ({ options, sources }) => {
+		const tests = ignore().add([...options.testFiles]);
+		return sources
+			.filter((file) => !DECLARATION.test(file.path))
+			.flatMap((file) => oversized(file, tests.ignores(file.path) ? options.test : options.source));
+	},
+});

package/src/standard-schema.ts

@@ -0,0 +1,22 @@
+// The Standard Schema V1 contract (standardschema.dev), copied as the specification recommends. Rule options accept any
+// conforming schema, so a consumer's own Effect version, or another schema library, validates them.
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+	readonly "~standard": {
+		readonly version: 1;
+		readonly vendor: string;
+		readonly validate: (value: unknown) => StandardResult<Output> | Promise<StandardResult<Output>>;
+		readonly types?: { readonly input: Input; readonly output: Output } | undefined;
+	};
+}
+
+export type StandardResult<Output> = { readonly value: Output; readonly issues?: undefined } | { readonly issues: ReadonlyArray<StandardIssue> };
+
+export interface StandardIssue {
+	readonly message: string;
+	readonly path?: ReadonlyArray<PropertyKey | { readonly key: PropertyKey }> | undefined;
+}
+
+const segment = (part: PropertyKey | { readonly key: PropertyKey }): string => String(typeof part === "object" ? part.key : part);
+
+export const describeIssue = (issue: StandardIssue): string =>
+	issue.path === undefined || issue.path.length === 0 ? issue.message : `${issue.path.map(segment).join(".")}: ${issue.message}`;