@okfit/cli 0.1.0 → 0.2.0

package/index.js

@@ -1,12 +1,17 @@
+import { ConfigMalformedError, ConfigPathNotFoundError, InitOverwriteError, VerifyConceptNotFoundError, VerifyUnsupportedFrontmatterError, renderFailure } from "./errors.js";
+import { buildConfigLayer, provideConfig } from "./config/layer.js";
+import { resolveBundleRoot, resolveProjectRoot } from "./config/anchor.js";
+import { DEFAULT_PROFILE_NAME, resolveProjectConfig } from "./config/resolve.js";
+import { runContext } from "./context/run.js";
+import { ContextEnvelope, ContextTag, ContextType, contextEnvelope, humanContext } from "./render/context.js";
+import { forDiagnostics, tally } from "./render/exit.js";
+import { collect, sort } from "./render/sort.js";
+import { JsonDiagnostic, JsonEnvelope, JsonErrorEnvelope, JsonSummary, json, jsonError } from "./render/json.js";
+import { CLI_VERSION } from "./version.js";
+import { CONFIG_RELATIVE_PATH, configValue, files, targetPaths } from "./init/scaffold.js";
+import { human, line, summary } from "./render/human.js";
+import { run } from "./validate/run.js";
+import { VerifyEnvelope, humanVerify, verifyEnvelope } from "./render/verify.js";
 import { rootCommand } from "./commands/root.js";
 
-//#region src/index.ts
-/**
-* The version string reported by `okfit --version`.
-*
-* @public
-*/
-const CLI_VERSION = "0.0.0";
-
-//#endregion
-export { CLI_VERSION, rootCommand };
+export { CLI_VERSION, CONFIG_RELATIVE_PATH, ConfigMalformedError, ConfigPathNotFoundError, ContextEnvelope, ContextTag, ContextType, DEFAULT_PROFILE_NAME, InitOverwriteError, JsonDiagnostic, JsonEnvelope, JsonErrorEnvelope, JsonSummary, VerifyConceptNotFoundError, VerifyEnvelope, VerifyUnsupportedFrontmatterError, buildConfigLayer, collect, configValue, contextEnvelope, files, forDiagnostics, human, humanContext, humanVerify, json, jsonError, line, provideConfig, renderFailure, resolveBundleRoot, resolveProjectConfig, resolveProjectRoot, rootCommand, run, runContext, sort, summary, tally, targetPaths, verifyEnvelope };

package/init/scaffold.js

@@ -0,0 +1,174 @@
+import { Effect, Option, Schema } from "effect";
+import { Concept, ConceptId, Derive, LoadedConcept, OKF_SPEC_VERSION } from "@okfit/core";
+import { MarkdownDocument, MarkdownFrontmatter, MarkdownParseOptions, YamlFrontmatter } from "@effected/markdown";
+
+//#region src/init/scaffold.ts
+/** `.config/okfit.toml`, relative to the project root (C-10). @public */
+const CONFIG_RELATIVE_PATH = ".config/okfit.toml";
+/**
+* C-1's three project-level names, in precedence order. `init` refuses when
+* ANY of them already exists in the target directory (C-9), so a fresh
+* `okfit init` beside a hand-written `.okfit.toml` cannot silently write a
+* second config the discovery order then shadows.
+*
+* Scope is `projectRoot` only, never the upward chain: an ancestor's config
+* is a legitimate discovery hit, not a collision.
+*
+* @public
+*/
+const PROJECT_CONFIG_NAMES = [
+	".okfit.toml",
+	"okfit.toml",
+	".config/okfit.toml"
+];
+/** C-22's directive, plus the blank line Tombi requires. @public */
+const SCHEMA_DIRECTIVE = "#:schema https://raw.githubusercontent.com/spencerbeggs/okfit/main/schemas/config/okfit-1.0.0.json\n\n";
+/**
+* K-23: the THIN override only — never the merged config. `bundle.path` is
+* the bundle root relative to the project root; `extensions: {}` satisfies
+* `OkfitConfig`'s one non-optional field (`CORE/OkfitConfig.ts:164`).
+* Everything else resolves from `DEFAULTS` and the profile at load time.
+* `actors.agent` is deliberately absent (K-24, P-17).
+*
+* @public
+*/
+const configValue = (options) => ({
+	bundle: {
+		path: options.bundlePath,
+		profile: options.profileName
+	},
+	extensions: {}
+});
+/**
+* Every path `init` will create, absolute, in write order, for the K-28
+* pre-flight: the three project-level config names, the bundle root's
+* `index.md`/`log.md`/`project.md`, then one `index.md` per layout directory
+* in `layout`'s own declared order — never re-sorted here. `Derive.renderIndex`
+* sorts its own `Subdirectories` section independently (C13), so this
+* function's order has no bearing on the rendered index text.
+*
+* @public
+*/
+const targetPaths = (options) => [
+	...PROJECT_CONFIG_NAMES.map((name) => `${options.projectRoot}/${name}`),
+	`${options.bundleRoot}/${options.layout.root.index}`,
+	`${options.bundleRoot}/${options.layout.root.log}`,
+	`${options.bundleRoot}/${options.layout.root.project}`,
+	...options.layout.directories.map((directory) => `${options.bundleRoot}/${directory.directory}/${options.layout.root.index}`)
+];
+/** Frontmatter capture on — the write seam's own precondition (`MD/index.d.ts:1907-1920`; `CORE/internal/reserved.ts:15` precedent). */
+const PARSE_OPTIONS = MarkdownParseOptions.make({ frontmatter: true });
+/**
+* The four keys `project.md` actually carries (contract section 3.4's
+* worked transcript) — deliberately NOT the full `Concept` class. `Concept`'s
+* `extensions` and `raw` fields are required, not `optionalKey`
+* (`CORE/Concept.ts:39-40`), so encoding a `Concept.make` value through
+* `Concept` itself would serialize `extensions: {}` and `raw: {}` into the
+* frontmatter block too (verified: `Schema.encodeSync(Concept)` against a
+* `Concept.make` value with empty `extensions`/`raw` includes both keys,
+* this session). `Bundle.load` re-decodes a file written with this narrower
+* schema exactly as it would one written with the full class —
+* `internal/conceptDecode.ts` derives `extensions`/`raw` from whatever keys
+* the frontmatter block actually carries, never from what wrote it (verified
+* with a `Bundle.load` round trip, this session) — so the narrower schema
+* costs nothing at read time and matches the transcript byte-for-byte.
+*/
+const ProjectFrontmatter = Schema.Struct({
+	type: Schema.Literal("Project"),
+	title: Schema.String,
+	description: Schema.String,
+	status: Schema.Literals([
+		"draft",
+		"stable",
+		"deprecated"
+	])
+});
+const PROJECT_DESCRIPTION = "What this project is, its boundaries, and its non-goals.";
+const capitalize = (name) => `${name.charAt(0).toUpperCase()}${name.slice(1)}`;
+const projectBody = (title) => [
+	`# ${title}`,
+	"",
+	"## Purpose",
+	"",
+	"Describe what this project is for in one paragraph.",
+	"",
+	"## Boundaries",
+	"",
+	"Describe what this project owns and what it deliberately leaves to others.",
+	"",
+	"## Non-goals",
+	"",
+	"List what this project will not do, so a reader never infers it from silence.",
+	""
+].join("\n");
+/**
+* The three root markdown files and the per-directory indexes (K-25 to
+* K-27, K-59). `project.md`'s frontmatter is written with
+* `MarkdownFrontmatter.setToString` — the INSERT path, since the body below
+* carries no frontmatter block of its own (`MD/index.d.ts:1959`,
+* `FrontmatterWriteError`'s own doc comment: "a document with no frontmatter
+* capture is the insert path, not an error"). The root `index.md` is
+* `Derive.renderIndex` over a `LoadedConcept` this function synthesizes from
+* the just-rendered `project.md` text, re-parsed with `MarkdownDocument.parse`
+* (K-59; `renderIndex` reads only `frontmatter.type`/`title`/`description`
+* and `path`, never `document`, `CORE/Derive.ts:75-101`, so the synthesized
+* value is faithful). Each per-directory `index.md` is the literal
+* `# <Directory>` — NOT `Derive.renderIndex`, which returns the empty string
+* for an empty concept list with no options (contract Judge notes item 2).
+*
+* @public
+*/
+const files = (options) => Effect.gen(function* () {
+	const { bundleRoot, layout, profileName, projectTitle, today } = options;
+	const frontmatterData = {
+		type: "Project",
+		title: projectTitle,
+		description: PROJECT_DESCRIPTION,
+		status: "draft"
+	};
+	const draftDocument = yield* MarkdownDocument.parse(projectBody(projectTitle), PARSE_OPTIONS);
+	const projectText = yield* MarkdownFrontmatter.setToString(ProjectFrontmatter, YamlFrontmatter)(draftDocument, frontmatterData);
+	const projectDocument = yield* MarkdownDocument.parse(projectText, PARSE_OPTIONS);
+	const projectConcept = LoadedConcept.make({
+		id: Option.getOrThrow(ConceptId.fromPath("project.md")),
+		path: "project.md",
+		frontmatter: Concept.make({
+			...frontmatterData,
+			extensions: {},
+			raw: frontmatterData
+		}),
+		document: projectDocument,
+		computationBody: Option.none()
+	});
+	const subdirectories = layout.directories.map((directory) => directory.directory);
+	const rootIndexText = Derive.renderIndex("", [projectConcept], {
+		okfVersion: OKF_SPEC_VERSION,
+		subdirectories
+	});
+	const logText = Derive.renderLogEntry({
+		date: today,
+		items: [`Initialized the bundle with the ${profileName} profile`]
+	});
+	const directoryFiles = layout.directories.map((directory) => ({
+		path: `${bundleRoot}/${directory.directory}/${layout.root.index}`,
+		contents: `# ${capitalize(directory.directory)}\n`
+	}));
+	return [
+		{
+			path: `${bundleRoot}/${layout.root.index}`,
+			contents: rootIndexText
+		},
+		{
+			path: `${bundleRoot}/${layout.root.log}`,
+			contents: logText
+		},
+		{
+			path: `${bundleRoot}/${layout.root.project}`,
+			contents: projectText
+		},
+		...directoryFiles
+	];
+});
+
+//#endregion
+export { CONFIG_RELATIVE_PATH, PROJECT_CONFIG_NAMES, SCHEMA_DIRECTIVE, configValue, files, targetPaths };

package/internal/exit.js

@@ -0,0 +1,14 @@
+//#region src/internal/exit.ts
+/**
+* K-7: exits `1` and `2` are a SUCCESSFUL run that found diagnostics, never
+* an Effect failure. The handler writes the code here and returns `void`.
+* The only writer of `process.exitCode` in this package.
+*
+* @public
+*/
+const setExitCode = (code) => {
+	process.exitCode = code;
+};
+
+//#endregion
+export { setExitCode };

package/internal/tty.js

@@ -0,0 +1,13 @@
+//#region src/internal/tty.ts
+/**
+* K-19: exactly the framework's own colour rule. Evaluated once per run at
+* the command boundary and passed to the renderers as a boolean, so every
+* renderer stays pure. The only reader of `process.stdout.isTTY`/`NO_COLOR`
+* in this package.
+*
+* @public
+*/
+const useColor = () => process.stdout.isTTY === true && process.env.NO_COLOR !== "1";
+
+//#endregion
+export { useColor };

package/package.js

@@ -0,0 +1,5 @@
+//#region package.json
+var version = "0.2.0";
+
+//#endregion
+export { version };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@okfit/cli",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"private": false,
 	"description": "The okfit command line: validate, lint, index, and inspect Open Knowledge Format (OKF) bundles.",
 	"keywords": [
@@ -37,10 +37,22 @@
 		"okfit": "bin/okfit.js"
 	},
 	"dependencies": {
-		"@effect/platform-node": "4.0.0-rc.109",
-		"@okfit/core": "0.1.0",
-		"@okfit/profiles": "0.1.0",
-		"effect": "4.0.0-rc.109"
+		"@effect/platform-node": "4.0.0-rc.112",
+		"@effected/app": "^0.15.0",
+		"@effected/cli": "^0.3.1",
+		"@effected/config-file": "^0.7.0",
+		"@effected/git": "^0.12.0",
+		"@effected/glob": "^0.5.0",
+		"@effected/jsonc": "^0.9.0",
+		"@effected/markdown": "^0.9.1",
+		"@effected/store": "^0.7.0",
+		"@effected/toml": "^0.6.0",
+		"@effected/walker": "^0.7.0",
+		"@effected/xdg": "^0.4.1",
+		"@effected/yaml": "^0.14.0",
+		"@okfit/core": "0.2.0",
+		"@okfit/profiles": "0.2.0",
+		"effect": "4.0.0-rc.112"
 	},
 	"engines": {
 		"node": ">=24.11.0"

package/render/context.js

@@ -0,0 +1,108 @@
+import { Schema } from "effect";
+
+//#region src/render/context.ts
+/** One `types[]` entry (M-15). @public */
+const ContextType = Schema.Struct({
+	name: Schema.String,
+	description: Schema.NullOr(Schema.String),
+	guidance: Schema.NullOr(Schema.String)
+});
+/** One `tags[]` entry (M-15). @public */
+const ContextTag = Schema.Struct({
+	name: Schema.String,
+	description: Schema.NullOr(Schema.String)
+});
+/**
+* M-15's envelope: schema 1, snake_case, orientation data only. Distinct
+* from `JsonEnvelope` (`render/json.ts`) — `context` never runs conformance
+* or lint checks, so there is no `diagnostics` array and no `exit_code`
+* field at all.
+*
+* Every field is `Schema.NullOr`, never `Schema.optionalKey`: a consumer
+* (the two hook scripts) reads a fixed key set and gets JSON `null` for an
+* absent value, rather than having to distinguish a missing key from a
+* null one. This is a deliberate difference from `JsonDiagnostic`'s
+* `range`, which is `optionalKey` and omitted when absent
+* (`render/json.ts:14,68`).
+*
+* `profile_requested` (final-review Important 1) is the profile name the
+* config asked for after the K-4 default rule — `resolveProjectConfig`'s
+* own `profileName` — and is `null` only when no config file was found at
+* all. `profile` keeps its original meaning (the resolved profile's name,
+* or `null` when the requested name is unknown or `"none"`). The two
+* differ exactly when a config named an unrecognised profile: `profile`
+* is `null` but `profile_requested` still names what was asked for, so a
+* consumer can tell "no profile configured" apart from "an unknown profile
+* was configured".
+*
+* @public
+*/
+const ContextEnvelope = Schema.Struct({
+	schema: Schema.Literal(1),
+	project_root: Schema.String,
+	bundle_root: Schema.String,
+	config_path: Schema.NullOr(Schema.String),
+	profile: Schema.NullOr(Schema.String),
+	profile_requested: Schema.NullOr(Schema.String),
+	index_path: Schema.String,
+	index_exists: Schema.Boolean,
+	actors: Schema.Struct({ agent: Schema.NullOr(Schema.String) }),
+	types: Schema.Array(ContextType),
+	tags: Schema.Array(ContextTag)
+});
+/**
+* Build the envelope from the merged config. `types`/`tags` sort by `name`
+* with plain code-unit comparison, never locale-dependent — the same rule
+* `render/sort.ts`'s K-17 comparator and
+* `packages/profiles/src/SoftwareProject.ts:119`'s own sort use.
+*
+* @public
+*/
+const contextEnvelope = (input) => ({
+	schema: 1,
+	project_root: input.projectRoot,
+	bundle_root: input.bundleRoot,
+	config_path: input.configPath,
+	profile: input.profile,
+	profile_requested: input.profileRequested,
+	index_path: input.indexPath,
+	index_exists: input.indexExists,
+	actors: { agent: input.config.actors?.agent ?? null },
+	types: Object.entries(input.config.types ?? {}).map(([name, decl]) => ({
+		name,
+		description: decl.description ?? null,
+		guidance: decl.guidance ?? null
+	})).toSorted((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0),
+	tags: Object.entries(input.config.tags ?? {}).map(([name, decl]) => ({
+		name,
+		description: decl.description ?? null
+	})).toSorted((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)
+});
+/**
+* The `human` format: a short header block, then one line per type and one
+* per tag. Pure; the caller pipes each line through `Console.log`.
+*
+* The `profile:` line reads `profile: (none) (requested NAME, unknown)`
+* when `profile` and `profile_requested` disagree over an actually-unknown
+* profile — never for the `"none"` or no-config cases, where a `null`
+* `profile` is expected, not an error.
+*
+* @public
+*/
+const humanContext = (envelope) => [
+	`project root: ${envelope.project_root}`,
+	`bundle root: ${envelope.bundle_root}`,
+	`config: ${envelope.config_path ?? "(none)"}`,
+	envelope.profile === null && envelope.profile_requested !== null && envelope.profile_requested !== "none" ? `profile: (none) (requested ${envelope.profile_requested}, unknown)` : `profile: ${envelope.profile ?? "(none)"}`,
+	`index.md: ${envelope.index_path} (${envelope.index_exists ? "exists" : "missing"})`,
+	`agent: ${envelope.actors.agent ?? "(unset)"}`,
+	"",
+	"types:",
+	...envelope.types.map((t) => `  ${t.name}  ${t.description ?? ""}`),
+	"",
+	"tags:",
+	...envelope.tags.map((t) => `  ${t.name}  ${t.description ?? ""}`)
+];
+
+//#endregion
+export { ContextEnvelope, ContextTag, ContextType, contextEnvelope, humanContext };

package/render/exit.js

@@ -0,0 +1,53 @@
+//#region src/render/exit.ts
+/**
+* One pass over the collected diagnostics. `core.conformance` entries are
+* always severity `error` (D-33); the counts are still taken from `severity`
+* so a future non-error conformance code cannot silently change the exit
+* code.
+*
+* @public
+*/
+const tally = (diagnostics) => {
+	let conformanceErrors = 0;
+	let lintErrors = 0;
+	let lintWarnings = 0;
+	let lintInfo = 0;
+	let profileErrors = 0;
+	for (const d of diagnostics) {
+		if (d.source === "core.conformance") {
+			if (d.severity === "error") conformanceErrors++;
+			continue;
+		}
+		if (d.source === "core.lint") {
+			if (d.severity === "error") lintErrors++;
+			else if (d.severity === "warning") lintWarnings++;
+			else lintInfo++;
+			continue;
+		}
+		if (d.severity === "error") profileErrors++;
+	}
+	return {
+		conformanceErrors,
+		lintErrors,
+		lintWarnings,
+		lintInfo,
+		profileErrors
+	};
+};
+/**
+* K-7/K-8's two lowest tiers: `2` when any conformance error is present, else
+* `1` when any lint OR profile error is present, else `0`. Warnings and info
+* never move it. `130`, `64` and `3` are set elsewhere — by the runtime's
+* interrupt branch, by the `ShowHelp` remap in `bin.ts`, and by the typed
+* errors' own `[Runtime.errorExitCode]` — so this function returns only
+* `0 | 1 | 2`.
+*
+* @public
+*/
+const forDiagnostics = (diagnostics) => {
+	const t = tally(diagnostics);
+	return t.conformanceErrors > 0 ? 2 : t.lintErrors + t.profileErrors > 0 ? 1 : 0;
+};
+
+//#endregion
+export { forDiagnostics, tally };

package/render/human.js

@@ -0,0 +1,68 @@
+import { sort } from "./sort.js";
+
+//#region src/render/human.ts
+/** The ANSI escape character, built from its code point so the source never carries a raw control byte. */
+const ESC = String.fromCharCode(27);
+/** ANSI SGR codes for the severity word only (K-19); reset after, never applied elsewhere. */
+const SEVERITY_COLOR = {
+	error: `${ESC}[31m`,
+	warning: `${ESC}[33m`,
+	info: `${ESC}[36m`
+};
+const RESET = `${ESC}[0m`;
+const colorize = (severity, color) => color ? `${SEVERITY_COLOR[severity]}${severity}${RESET}` : severity;
+/**
+* K-16. With a range:
+* `<file>:<range.line + 1>:<range.character + 1> <severity> <code> <message>`.
+* Without one: `<file> <severity> <code> <message>`. `file: ""` renders as
+* the literal `(bundle)`. Core's range is zero-based (D-32,
+* `CORE/Diagnostic.ts:49-57`); the `+ 1`s here are the only place it becomes
+* one-based. Colour, when `color` is `true`, wraps ONLY the severity word
+* (K-19) — never the code, the path, or the message.
+*
+* @public
+*/
+const line = (diagnostic, options) => {
+	const color = options?.color ?? false;
+	const file = diagnostic.file === "" ? "(bundle)" : diagnostic.file;
+	const severity = colorize(diagnostic.severity, color);
+	return `${diagnostic.range === void 0 ? file : `${file}:${diagnostic.range.line + 1}:${diagnostic.range.character + 1}`} ${severity} ${diagnostic.code} ${diagnostic.message}`;
+};
+/**
+* `sort` then `line` over the whole set: the exact stdout body of
+* `--format human`, one array element per stdout line.
+*
+* @public
+*/
+const human = (diagnostics, options) => sort(diagnostics).map((d) => line(d, options));
+/**
+* K-20, verbatim and unpluralised —
+* `<E> errors, <W> warnings, <I> info in <N> concepts (<root>)`. `root` is
+* pre-rendered by the caller: relative to cwd when under it, absolute
+* otherwise (K-51).
+*
+* @public
+*/
+const summary = (counts, root) => `${counts.errors} errors, ${counts.warnings} warnings, ${counts.info} info in ${counts.concepts} concepts (${root})`;
+/**
+* The one K-51 display-path rule, shared by both `commands/validate.ts`'s
+* `summary` root and `commands/init.ts`'s success line: `target` relative
+* to `cwd` when it is under it, absolute otherwise. Three cases, in order:
+*
+* 1. `target === cwd` (`path.relative` returns `""`): the literal `.`.
+* 2. The relative form starts with `..`, or is itself absolute (a target on
+*    a different root than `cwd`, where `Path.relative` can return an
+*    absolute path unchanged depending on the platform): `target`
+*    unchanged, absolute.
+* 3. Otherwise: the relative form.
+*
+* @internal
+*/
+const displayRoot = (cwd, target, path) => {
+	const relative = path.relative(cwd, target);
+	if (relative === "") return ".";
+	return relative.startsWith("..") || path.isAbsolute(relative) ? target : relative;
+};
+
+//#endregion
+export { displayRoot, human, line, summary };

package/render/json.js

@@ -0,0 +1,126 @@
+import { tally } from "./exit.js";
+import { sort } from "./sort.js";
+import { Schema } from "effect";
+import { DiagnosticRange, DiagnosticSeverity } from "@okfit/core";
+
+//#region src/render/json.ts
+/** One entry of the `diagnostics` array (K-21). @public */
+const JsonDiagnostic = Schema.Struct({
+	source: Schema.Literals([
+		"core.conformance",
+		"core.lint",
+		"profile"
+	]),
+	file: Schema.String,
+	code: Schema.String,
+	severity: DiagnosticSeverity,
+	message: Schema.String,
+	range: Schema.optionalKey(DiagnosticRange)
+});
+/** @public */
+const JsonSummary = Schema.Struct({
+	conformance_errors: Schema.Number,
+	lint_errors: Schema.Number,
+	lint_warnings: Schema.Number,
+	lint_info: Schema.Number,
+	profile_errors: Schema.Number,
+	concepts: Schema.Number
+});
+/**
+* K-21's success envelope, snake_case. `exit_code` is `0 | 1 | 2` only: an
+* infrastructure failure never produces this envelope, it produces the
+* `JsonErrorEnvelope` (K-22).
+*
+* @public
+*/
+const JsonEnvelope = Schema.Struct({
+	schema: Schema.Literal(1),
+	okfit_version: Schema.String,
+	okf_version: Schema.String,
+	root: Schema.String,
+	profile: Schema.NullOr(Schema.String),
+	exit_code: Schema.Literals([
+		0,
+		1,
+		2
+	]),
+	summary: JsonSummary,
+	diagnostics: Schema.Array(JsonDiagnostic)
+});
+/** K-22's envelope: the ONLY thing stdout carries under `--format json` on an exit-3 failure. @public */
+const JsonErrorEnvelope = Schema.Struct({
+	schema: Schema.Literal(1),
+	okfit_version: Schema.String,
+	exit_code: Schema.Literal(3),
+	error: Schema.Struct({
+		tag: Schema.String,
+		message: Schema.String
+	})
+});
+const toJsonDiagnostic = (d) => ({
+	source: d.source,
+	file: d.file,
+	code: d.code,
+	severity: d.severity,
+	message: d.message,
+	...d.range === void 0 ? {} : { range: d.range }
+});
+/**
+* Build the success envelope. `diagnostics` is sorted here with the same
+* `sort` the human renderer uses (K-21's "diagnostics are in the K-17
+* order"); `range` passes through as core computed it, zero-based.
+*
+* The value returned is in `Type` form (its `range`s are `DiagnosticRange`
+* instances). What stdout carries is `Schema.encodeSync(JsonEnvelope)` of it,
+* `JSON.stringify`-ed — one document, no trailing text.
+*
+* @public
+*/
+const json = (input) => {
+	const t = tally(input.diagnostics);
+	return {
+		schema: 1,
+		okfit_version: input.okfitVersion,
+		okf_version: input.okfVersion,
+		root: input.root,
+		profile: input.profile,
+		exit_code: input.exitCode,
+		summary: {
+			conformance_errors: t.conformanceErrors,
+			lint_errors: t.lintErrors,
+			lint_warnings: t.lintWarnings,
+			lint_info: t.lintInfo,
+			profile_errors: t.profileErrors,
+			concepts: input.concepts
+		},
+		diagnostics: sort(input.diagnostics).map(toJsonDiagnostic)
+	};
+};
+/** The error's `_tag` when it has one, else its constructor name; `"UnknownError"` for a non-object value. */
+const tagOf = (error) => {
+	if (typeof error !== "object" || error === null) return "UnknownError";
+	const tag = error._tag;
+	if (typeof tag === "string") return tag;
+	return error.constructor?.name ?? "UnknownError";
+};
+/** The error's `message` when it has one as a string, else `String(error)`. */
+const messageOf = (error) => {
+	if (typeof error === "object" && error !== null && "message" in error) {
+		const message = error.message;
+		if (typeof message === "string") return message;
+	}
+	return String(error);
+};
+/** K-22. `tag` is the error's `_tag` when it has one, else its constructor name. @public */
+const jsonError = (error, okfitVersion) => ({
+	schema: 1,
+	okfit_version: okfitVersion,
+	exit_code: 3,
+	error: {
+		tag: tagOf(error),
+		message: messageOf(error)
+	}
+});
+
+//#endregion
+export { JsonDiagnostic, JsonEnvelope, JsonErrorEnvelope, JsonSummary, json, jsonError };

package/render/sort.js

@@ -0,0 +1,46 @@
+//#region src/render/sort.ts
+const toRendered = (source) => (entry) => ({
+	source,
+	file: entry.file,
+	code: entry.code,
+	severity: entry.severity,
+	message: entry.message,
+	...entry.range === void 0 ? {} : { range: entry.range }
+});
+/**
+* Tag core's two arrays and profiles' one, in producer order. Not named
+* `merge`: `OkfitConfig.merge` already owns that word in this codebase.
+*
+* @public
+*/
+const collect = (conformance, lint, profile) => [
+	...conformance.map(toRendered("core.conformance")),
+	...lint.map(toRendered("core.lint")),
+	...profile.map(toRendered("profile"))
+];
+/** Range-less entries sort before ranged ones within the same file; ranged entries by `offset`. */
+const compareRange = (a, b) => {
+	if (a.range === void 0 && b.range === void 0) return 0;
+	if (a.range === void 0) return -1;
+	if (b.range === void 0) return 1;
+	return a.range.offset - b.range.offset;
+};
+/**
+* K-17: `file` ascending (so `""` — the bundle-level finding — leads), then
+* range-less before ranged within a file, then `range.offset` ascending, then
+* `code`. Plain code-unit comparison, never locale-dependent (the same rule
+* profiles' own `check` sorts by, `PROFILES/SoftwareProject.ts:119`). Stable:
+* implemented with `toSorted`, which is specified as stable.
+*
+* @public
+*/
+const sort = (diagnostics) => diagnostics.toSorted((a, b) => {
+	if (a.file !== b.file) return a.file < b.file ? -1 : 1;
+	const byRange = compareRange(a, b);
+	if (byRange !== 0) return byRange;
+	if (a.code !== b.code) return a.code < b.code ? -1 : 1;
+	return 0;
+});
+
+//#endregion
+export { collect, sort };