@shivaedev/quality 0.2.0 → 0.3.1

package/src/report/guard.ts

@@ -0,0 +1,46 @@
+import type { GuardProblem, GuardResult } from "../baseline/guard.ts";
+import type { Base } from "../git/base.ts";
+import { plural } from "./plural.ts";
+
+export interface GuardContext {
+	readonly baseline: string;
+	readonly config: string;
+	readonly base: Base;
+}
+
+const problemLine = (problem: GuardProblem, context: GuardContext): string => {
+	switch (problem._tag) {
+		case "Added":
+			return `${problem.entry.rule} ${problem.entry.file} is new, at ${problem.entry.count}.`;
+		case "Raised":
+			return `${problem.entry.rule} ${problem.entry.file} rose to ${problem.entry.count} from ${problem.base.count}.`;
+		case "Unadopted":
+			return `${problem.rule} is newly baselined in ${plural(problem.entries, "file")} without being named under \`adopt\` in ${context.config}.`;
+		case "NothingAdopted":
+			return `\`adopt\` in ${context.config} names ${problem.rule}, which has nothing baselined. Remove it.`;
+	}
+};
+
+const against = (base: Base): string => `${base.ref} (merge base ${base.commit.slice(0, 12)})`;
+
+const held = (result: GuardResult): string =>
+	[
+		...(result.moved > 0 ? [`${plural(result.moved, "entry", "entries")} followed moved files`] : []),
+		...(result.adopted.length > 0 ? [`adopted ${result.adopted.join(", ")}`] : []),
+	]
+		.map((part) => `; ${part}`)
+		.join("");
+
+export const renderGuard = (result: GuardResult, context: GuardContext): string => {
+	if (result.problems.length === 0) {
+		return `quality: ${context.baseline} holds against ${against(context.base)}${held(result)}.`;
+	}
+	return [
+		[
+			`error ${context.baseline} grew against ${against(context.base)}`,
+			`  The baseline only shrinks. Fix new violations instead of baselining them; a rule enters the baseline for the first time only while \`adopt\` names it.`,
+			...result.problems.map((problem) => `  ${problemLine(problem, context)}`),
+		].join("\n"),
+		`quality: baseline check failed with ${plural(result.problems.length, "problem")}.`,
+	].join("\n\n");
+};

package/src/report/render.ts

@@ -1,4 +1,4 @@
-import { describeEntry, describeTally, type Regression } from "../baseline/compare.ts";
+import 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";
@@ -19,7 +19,7 @@ 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.`;
+	`  ${regression.entry.file} is over its baseline: ${regression.count} against ${regression.entry.count} baselined.`;
 
 const heading = (label: string, rule: string, violations: ReadonlyArray<Violation>, context: ReportContext): ReadonlyArray<string> => {
 	const description = context.descriptions.get(rule);

package/src/report/stale.ts

@@ -8,8 +8,8 @@ interface StaleFiles {
 	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 section = (label: string, file: string, guidance: string, lines: ReadonlyArray<string>): ReadonlyArray<string> =>
+	lines.length === 0 ? [] : [[`${label} ${file}: ${plural(lines.length, "stale entry", "stale entries")}`, `  ${guidance}`, ...lines].join("\n")];
 
 const baselineLine = ({ entry, problem }: StaleBaselineEntry): string => `  ${entry.rule} ${entry.file} ${problem}.`;
 
@@ -18,11 +18,19 @@ const registryLine = ({ entry, problem }: StaleRegistryEntry): string =>
 
 export const staleSections = (outcome: Outcome, files: StaleFiles): ReadonlyArray<string> => [
 	...section(
+		"error",
 		files.baseline,
-		"The baseline only shrinks. Run `quality baseline prune` to drop fixed debt; prune never adds or raises an entry.",
+		"An entry for a rule that is off or unknown covers nothing. Run `quality baseline prune` to drop it.",
 		outcome.staleBaseline.map(baselineLine),
 	),
 	...section(
+		"note",
+		files.baseline,
+		"These pass, and `quality baseline tighten` lowers them when their files change. `quality baseline prune` lowers them all.",
+		outcome.looseBaseline.map(baselineLine),
+	),
+	...section(
+		"error",
 		files.registry,
 		"Every registered exception must still apply. Remove the entries whose exception is gone.",
 		outcome.staleRegistry.map(registryLine),

package/src/rule.ts

@@ -4,10 +4,9 @@ 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;
+	readonly count?: number | undefined;
+	readonly threshold?: number | undefined;
 }
 
 export type Findings = ReadonlyArray<Finding>;
@@ -36,6 +35,7 @@ export type Configured =
 export interface Rule<Id extends string = string, Input = unknown> {
 	readonly id: Id;
 	readonly description: string;
+	readonly registrable?: boolean;
 	// Method syntax keeps rules with different options in one list; configure validates its input at runtime.
 	configure(options: Input | undefined): Promise<Configured>;
 }
@@ -43,6 +43,7 @@ export interface Rule<Id extends string = string, Input = unknown> {
 interface RuleDefinition<Id extends string, Options> {
 	readonly id: Id;
 	readonly description: string;
+	readonly registrable?: false;
 	readonly check: (context: RuleContext<Options>) => Findings | PromiseLike<Findings>;
 }
 
@@ -73,10 +74,6 @@ const configureWith =
 		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>(
@@ -86,5 +83,5 @@ export function defineRule<const Id extends string, Input, Options>(
 		definition.options === undefined
 			? configureWith(noOptions, definition.check, undefined)
 			: configureWith(definition.options, definition.check, {});
-	return { configure, description: definition.description, id: definition.id };
+	return { configure, description: definition.description, id: definition.id, registrable: definition.registrable ?? true };
 }

package/src/rules/built-in.ts

@@ -1,3 +1,23 @@
+import { maxPerFile } from "./comments/max-per-file.ts";
+import { noBanner } from "./comments/no-banner.ts";
+import { noJsdoc } from "./comments/no-jsdoc.ts";
+import { noLineReference } from "./comments/no-line-reference.ts";
+import { noPrReference } from "./comments/no-pr-reference.ts";
+import { noTodo } from "./comments/no-todo.ts";
 import { maxLines } from "./max-lines.ts";
+import { biomeOverrides } from "./suppressions/biome-overrides.ts";
+import { noDoubleCast } from "./suppressions/no-double-cast.ts";
+import { noInline } from "./suppressions/no-inline.ts";
 
-export const builtInRules = [maxLines] as const;
+export const builtInRules = [
+	maxLines,
+	noJsdoc,
+	noLineReference,
+	noPrReference,
+	noBanner,
+	noTodo,
+	maxPerFile,
+	noInline,
+	noDoubleCast,
+	biomeOverrides,
+] as const;

package/src/rules/comments/kinds.ts

@@ -0,0 +1,45 @@
+import { Effect, Schema } from "effect";
+import { SUPPRESSIONS } from "../suppressions/directives.ts";
+import type { SourceComment } from "./scan.ts";
+
+export const DEFAULT_PRAGMAS: ReadonlyArray<string> = [
+	"@vitest-environment",
+	"@vitest-environment-options",
+	"@jest-environment",
+	"@jsx",
+	"@jsxFrag",
+	"@jsxImportSource",
+	"@jsxRuntime",
+];
+
+export const Pragmas = Schema.Array(Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed(DEFAULT_PRAGMAS)));
+
+const DIRECTIVES: ReadonlyArray<RegExp> = [
+	...SUPPRESSIONS,
+	/^@ts-/,
+	/^biome-ignore/,
+	/^(?:eslint|oxlint|stylelint)-(?:disable|enable)/,
+	/^[#@]__(?:PURE|NO_SIDE_EFFECTS)__/,
+	/^(?:c8|v8|istanbul) ignore/,
+];
+
+const TRIPLE_SLASH = /^\/\/\/\s*</;
+
+const contentOf = (comment: SourceComment): ReadonlyArray<string> => comment.body.filter((line) => line !== "");
+
+const startsWithTag = (line: string, tags: ReadonlyArray<string>): boolean =>
+	tags.some((tag) => line === tag || line.startsWith(`${tag} `) || line.startsWith(`${tag}\t`));
+
+export const textOf = (comment: SourceComment): string => comment.body.join("\n");
+
+export const isJsdoc = (comment: SourceComment): boolean => comment.kind === "block" && comment.text.startsWith("/**") && comment.text !== "/**/";
+
+export const isPragma = (comment: SourceComment, pragmas: ReadonlyArray<string>): boolean => {
+	const content = contentOf(comment);
+	return content.length > 0 && content.every((line) => startsWithTag(line, pragmas));
+};
+
+export const isDirective = (comment: SourceComment): boolean => {
+	const first = contentOf(comment)[0] ?? "";
+	return TRIPLE_SLASH.test(comment.text) || DIRECTIVES.some((directive) => directive.test(first));
+};

package/src/rules/comments/max-per-file.ts

@@ -0,0 +1,46 @@
+import { Effect, Schema } from "effect";
+import { plural } from "../../report/plural.ts";
+import { defineRule, type Finding, type SourceFile } from "../../rule.ts";
+import { isDirective, isPragma, Pragmas } from "./kinds.ts";
+import { commentsOf, type SourceComment } from "./scan.ts";
+
+const MaxPerFileOptions = Schema.Struct({
+	max: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)).pipe(Schema.withDecodingDefaultKey(Effect.succeed(2))),
+	allow: Pragmas,
+});
+
+const continues = (previous: SourceComment | undefined, comment: SourceComment): boolean =>
+	previous !== undefined &&
+	previous.kind === "line" &&
+	comment.kind === "line" &&
+	previous.ownLine &&
+	comment.ownLine &&
+	comment.line === previous.endLine + 1;
+
+const commentBlocks = (comments: ReadonlyArray<SourceComment>): ReadonlyArray<SourceComment> =>
+	comments.filter((comment, index) => !continues(comments[index - 1], comment));
+
+const overCap = (file: SourceFile, max: number, allow: ReadonlyArray<string>): ReadonlyArray<Finding> => {
+	const counted = commentsOf(file).filter((comment) => !isDirective(comment) && !isPragma(comment, allow));
+	const blocks = commentBlocks(counted);
+	const first = blocks[max];
+	return first === undefined
+		? []
+		: [
+				{
+					file: file.path,
+					line: first.line,
+					count: blocks.length - max,
+					message: `${plural(blocks.length, "comment", "comments")} against a limit of ${max}.`,
+					threshold: max,
+				},
+			];
+};
+
+export const maxPerFile = defineRule({
+	id: "comments/max-per-file",
+	description:
+		"A file that needs more than a few comments does too much, or its comments narrate the code. Delete the comments that restate the code, then split the file.",
+	options: Schema.toStandardSchemaV1(MaxPerFileOptions, { parseOptions: { errors: "all", onExcessProperty: "error" } }),
+	check: ({ options, sources }) => sources.flatMap((file) => overCap(file, options.max, options.allow)),
+});

package/src/rules/comments/no-banner.ts

@@ -0,0 +1,10 @@
+import { definePatternRule } from "./pattern-rule.ts";
+
+const DIVIDER = "[-=*#~_+/\\\\─━═┄┈]{3,}";
+
+export const noBanner = definePatternRule({
+	id: "comments/no-banner",
+	description: "Banners, dividers and regions mark a file that does several jobs. Split the file along those sections instead.",
+	patterns: [new RegExp(`^${DIVIDER}|${DIVIDER}$`, "m"), /^#(?:end)?region\b/m],
+	message: (match) => `Banner or divider: "${match}".`,
+});

package/src/rules/comments/no-jsdoc.ts

@@ -0,0 +1,18 @@
+import { Schema } from "effect";
+import { defineRule } from "../../rule.ts";
+import { isDirective, isJsdoc, isPragma, Pragmas } from "./kinds.ts";
+import { commentsOf } from "./scan.ts";
+
+const NoJsdocOptions = Schema.Struct({ allow: Pragmas });
+
+export const noJsdoc = defineRule({
+	id: "comments/no-jsdoc",
+	description: "Names and types already say what a JSDoc block repeats. Delete it, and keep a reason the code cannot show as a short // comment.",
+	options: Schema.toStandardSchemaV1(NoJsdocOptions, { parseOptions: { errors: "all", onExcessProperty: "error" } }),
+	check: ({ options, sources }) =>
+		sources.flatMap((file) =>
+			commentsOf(file)
+				.filter((comment) => isJsdoc(comment) && !isPragma(comment, options.allow) && !isDirective(comment))
+				.map((comment) => ({ file: file.path, line: comment.line, message: "JSDoc block." })),
+		),
+});

package/src/rules/comments/no-line-reference.ts

@@ -0,0 +1,11 @@
+import { definePatternRule } from "./pattern-rule.ts";
+
+const SOURCE_EXTENSION =
+	"(?:[cm]?[jt]sx?|json5?|mdx?|css|scss|less|html?|vue|svelte|astro|ya?ml|toml|sql|prisma|graphql|gql|go|rs|py|rb|java|kt|swift|sh)";
+
+export const noLineReference = definePatternRule({
+	id: "comments/no-line-reference",
+	description: "A line number goes stale with the next edit. Name the function, type, test or setting instead.",
+	patterns: [new RegExp(`[\\w./@-]*\\.${SOURCE_EXTENSION}(?::\\d+|#L\\d+)`, "i"), /(?<![\w-])lines?\s+\d+/i],
+	message: (match) => `Refers to a line: "${match}".`,
+});

package/src/rules/comments/no-pr-reference.ts

@@ -0,0 +1,13 @@
+import { definePatternRule } from "./pattern-rule.ts";
+
+export const noPrReference = definePatternRule({
+	id: "comments/no-pr-reference",
+	description: "History belongs in version control, not in the code. State the reason itself, so the comment holds without the link.",
+	patterns: [
+		/\b(?:PR|MR|pull request|merge request|issue|ticket)s?\s*#?\d+\b/i,
+		/\/(?:pull|pulls|issues|merge_requests)\/\d+/,
+		/\bGH-\d+\b/,
+		/(?<![\w&/#-])#\d+\b/,
+	],
+	message: (match) => `Refers to a pull request or issue: "${match}".`,
+});

package/src/rules/comments/no-todo.ts

@@ -0,0 +1,8 @@
+import { definePatternRule } from "./pattern-rule.ts";
+
+export const noTodo = definePatternRule({
+	id: "comments/no-todo",
+	description: "A TODO in the code is never done. Do the work now, or track it where the repository tracks work.",
+	patterns: [/\b(?:TODO|FIXME|XXX)\b/, /@todo\b/i],
+	message: (match) => `Marks unfinished work: "${match}".`,
+});

package/src/rules/comments/pattern-rule.ts

@@ -0,0 +1,28 @@
+import { defineRule, type Finding, type Rule } from "../../rule.ts";
+import { isDirective, textOf } from "./kinds.ts";
+import { commentsOf, type SourceComment } from "./scan.ts";
+
+interface PatternRule<Id extends string> {
+	readonly id: Id;
+	readonly description: string;
+	readonly patterns: ReadonlyArray<RegExp>;
+	readonly message: (match: string) => string;
+}
+
+const firstMatch = (comment: SourceComment, patterns: ReadonlyArray<RegExp>): string | undefined => {
+	const text = textOf(comment);
+	return patterns.map((pattern) => pattern.exec(text)?.[0]).find((match) => match !== undefined);
+};
+
+export const definePatternRule = <const Id extends string>({ description, id, message, patterns }: PatternRule<Id>): Rule<Id, undefined> =>
+	defineRule({
+		id,
+		description,
+		check: ({ sources }) =>
+			sources.flatMap((file) =>
+				commentsOf(file).flatMap((comment): ReadonlyArray<Finding> => {
+					const match = isDirective(comment) ? undefined : firstMatch(comment, patterns);
+					return match === undefined ? [] : [{ file: file.path, line: comment.line, message: message(match) }];
+				}),
+			),
+	});

package/src/rules/comments/scan.ts

@@ -0,0 +1,80 @@
+import ts from "typescript";
+import type { SourceFile } from "../../rule.ts";
+import { parse } from "../syntax.ts";
+
+export interface SourceComment {
+	readonly kind: "block" | "line";
+	readonly text: string;
+	readonly body: ReadonlyArray<string>;
+	readonly line: number;
+	readonly endLine: number;
+	readonly ownLine: boolean;
+}
+
+const DECLARATION = /\.d\.[cm]?ts$/;
+
+const commentRanges = (source: ts.SourceFile): ReadonlyArray<ts.CommentRange> => {
+	const ranges = new Map<number, ts.CommentRange>();
+	const jsxText: Array<ts.Node> = [];
+	const add = (found: ReadonlyArray<ts.CommentRange> | undefined) => {
+		for (const range of found ?? []) {
+			ranges.set(range.pos, range);
+		}
+	};
+	const visit = (node: ts.Node) => {
+		if (node.kind === ts.SyntaxKind.JsxText) {
+			jsxText.push(node);
+		}
+		add(ts.getLeadingCommentRanges(source.text, node.pos));
+		add(ts.getTrailingCommentRanges(source.text, node.end));
+		for (const child of node.getChildren(source)) {
+			visit(child);
+		}
+	};
+	visit(source);
+	return [...ranges.values()]
+		.filter((range) => !jsxText.some((text) => range.pos >= text.pos && range.pos < text.end))
+		.sort((left, right) => left.pos - right.pos);
+};
+
+export const bodyOf = (kind: SourceComment["kind"], text: string): ReadonlyArray<string> =>
+	kind === "line"
+		? [text.slice(2).trim()]
+		: text
+				.slice(2, -2)
+				.split("\n")
+				.map((line) => line.trim().replace(/^\*(?=\s|$)\s*/, ""));
+
+const toComment = (source: ts.SourceFile, range: ts.CommentRange): SourceComment => {
+	const kind = range.kind === ts.SyntaxKind.SingleLineCommentTrivia ? "line" : "block";
+	const text = source.text.slice(range.pos, range.end);
+	const start = source.getLineAndCharacterOfPosition(range.pos);
+	const lineStart = source.getPositionOfLineAndCharacter(start.line, 0);
+	return {
+		body: bodyOf(kind, text),
+		endLine: source.getLineAndCharacterOfPosition(range.end).line + 1,
+		kind,
+		line: start.line + 1,
+		ownLine: source.text.slice(lineStart, range.pos).trim() === "",
+		text,
+	};
+};
+
+const scanned = new WeakMap<SourceFile, ReadonlyArray<SourceComment>>();
+
+const scan = (file: SourceFile): ReadonlyArray<SourceComment> => {
+	const source = parse(file);
+	return source === undefined ? [] : commentRanges(source).map((range) => toComment(source, range));
+};
+
+export const scanComments = (file: SourceFile): ReadonlyArray<SourceComment> => {
+	const cached = scanned.get(file);
+	if (cached !== undefined) {
+		return cached;
+	}
+	const comments = scan(file);
+	scanned.set(file, comments);
+	return comments;
+};
+
+export const commentsOf = (file: SourceFile): ReadonlyArray<SourceComment> => (DECLARATION.test(file.path) ? [] : scanComments(file));

package/src/rules/max-lines.ts

@@ -16,7 +16,14 @@ const MaxLinesOptions = Schema.Struct({
 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.` }];
+		: [
+				{
+					count: file.lines.length - limit,
+					file: file.path,
+					message: `${file.lines.length} lines exceeds the ${limit}-line limit.`,
+					threshold: limit,
+				},
+			];
 
 export const maxLines = defineRule({
 	id: "structure/max-lines",

package/src/rules/suppressions/biome/configs.ts

@@ -0,0 +1,50 @@
+import { posix } from "node:path";
+import type { RuleInputs } from "../../../rule.ts";
+import { itemsOf, type Json, member, parseJsonc, textOf } from "./json.ts";
+
+export type Config =
+	| { readonly _tag: "Config"; readonly path: string; readonly base: string; readonly json: Json }
+	| { readonly _tag: "Unreadable"; readonly path: string; readonly reason: string };
+
+const ROOT_CONFIGS: ReadonlyArray<string> = ["biome.json", "biome.jsonc"];
+
+const NESTED = /(?:^|\/)biome\.jsonc?$/;
+
+const directoryOf = (path: string): string => (posix.dirname(path) === "." ? "" : posix.dirname(path));
+
+const localExtends = (path: string, json: Json): ReadonlyArray<string> => {
+	const node = member(json, "extends");
+	const entries = node?._tag === "Array" ? itemsOf(node).flatMap((item) => textOf(item) ?? []) : [textOf(node) ?? ""];
+	return entries.filter((entry) => entry.startsWith(".")).map((entry) => posix.join(posix.dirname(path), entry));
+};
+
+const load = async (readText: RuleInputs["readText"], path: string, base: string, seen: Set<string>): Promise<ReadonlyArray<Config>> => {
+	if (seen.has(path)) {
+		return [];
+	}
+	seen.add(path);
+	const text = await readText(path);
+	if (text === undefined) {
+		return [{ _tag: "Unreadable", path, reason: "the file does not exist" }];
+	}
+	const parsed = parseJsonc(path, text);
+	if (parsed._tag === "Unreadable") {
+		return [{ _tag: "Unreadable", path, reason: parsed.reason }];
+	}
+	const extended = await Promise.all(localExtends(path, parsed.json).map((target) => load(readText, target, base, seen)));
+	return [{ _tag: "Config", base, json: parsed.json, path }, ...extended.flat()];
+};
+
+const rootConfig = async (readText: RuleInputs["readText"]): Promise<string | undefined> => {
+	const present = await Promise.all(ROOT_CONFIGS.map(async (path) => ((await readText(path)) === undefined ? [] : [path])));
+	return present.flat()[0];
+};
+
+export const biomeConfigs = async ({ files, readText }: RuleInputs): Promise<ReadonlyArray<Config>> => {
+	const seen = new Set<string>();
+	const root = await rootConfig(readText);
+	const nested = files.filter((path) => NESTED.test(path) && path !== root);
+	const roots = root === undefined ? [] : await load(readText, root, "", seen);
+	const below = await Promise.all(nested.map((path) => load(readText, path, directoryOf(path), seen)));
+	return [...roots, ...below.flat()];
+};

package/src/rules/suppressions/biome/json.ts

@@ -0,0 +1,55 @@
+import ts from "typescript";
+
+export type Json =
+	| { readonly _tag: "Object"; readonly line: number; readonly entries: ReadonlyMap<string, Json> }
+	| { readonly _tag: "Array"; readonly line: number; readonly items: ReadonlyArray<Json> }
+	| { readonly _tag: "Value"; readonly line: number; readonly value: string | boolean | undefined };
+
+export type Parsed = { readonly _tag: "Parsed"; readonly json: Json } | { readonly _tag: "Unreadable"; readonly reason: string };
+
+const LITERALS: ReadonlyMap<ts.SyntaxKind, boolean> = new Map([
+	[ts.SyntaxKind.TrueKeyword, true],
+	[ts.SyntaxKind.FalseKeyword, false],
+]);
+
+const scalarOf = (node: ts.Expression): string | boolean | undefined => (ts.isStringLiteral(node) ? node.text : LITERALS.get(node.kind));
+
+const entryOf = (source: ts.JsonSourceFile, property: ts.ObjectLiteralElementLike): ReadonlyArray<readonly [string, Json]> =>
+	ts.isPropertyAssignment(property) && (ts.isStringLiteral(property.name) || ts.isIdentifier(property.name))
+		? [[property.name.text, toJson(source, property.initializer)]]
+		: [];
+
+const toJson = (source: ts.JsonSourceFile, node: ts.Expression): Json => {
+	const line = source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1;
+	if (ts.isObjectLiteralExpression(node)) {
+		return { _tag: "Object", entries: new Map(node.properties.flatMap((property) => entryOf(source, property))), line };
+	}
+	if (ts.isArrayLiteralExpression(node)) {
+		return { _tag: "Array", items: node.elements.map((element) => toJson(source, element)), line };
+	}
+	return { _tag: "Value", line, value: scalarOf(node) };
+};
+
+export const parseJsonc = (path: string, text: string): Parsed => {
+	const error = ts.parseConfigFileTextToJson(path, text).error;
+	const source = ts.parseJsonText(path, text);
+	const root = source.statements[0]?.expression;
+	if (error !== undefined || root === undefined) {
+		return {
+			_tag: "Unreadable",
+			reason: error === undefined ? "it is empty" : ts.flattenDiagnosticMessageText(error.messageText, " ").replace(/\.$/, ""),
+		};
+	}
+	return { _tag: "Parsed", json: toJson(source, root) };
+};
+
+export const member = (node: Json | undefined, key: string): Json | undefined => (node?._tag === "Object" ? node.entries.get(key) : undefined);
+
+export const entriesOf = (node: Json | undefined): ReadonlyArray<readonly [string, Json]> => (node?._tag === "Object" ? [...node.entries] : []);
+
+export const itemsOf = (node: Json | undefined): ReadonlyArray<Json> => (node?._tag === "Array" ? node.items : []);
+
+export const textOf = (node: Json | undefined): string | undefined =>
+	node?._tag === "Value" && typeof node.value === "string" ? node.value : undefined;
+
+export const isFalse = (node: Json | undefined): boolean => node?._tag === "Value" && node.value === false;