@goodbones/core 0.1.0-beta.1 → 0.1.0-beta.10

package/src/domain/report.ts

@@ -0,0 +1,203 @@
+// A campaign's `report` term names a pattern no parser of ours sees: a type
+// error, a lint finding from another tool, anything a program prints one
+// line per occurrence. This is the vocabulary such a report is read into —
+// a diagnostic with a file, a position, a code and a message — and the
+// readers for the formats a report comes in. Pure: text in, diagnostics out.
+// Running the command or reading the file is the report source's business.
+
+export type Diagnostic = {
+  // Repo-relative, forward slashes.
+  readonly file: string;
+  // Zero-based, as a syntax match's range is.
+  readonly line: number;
+  readonly column: number;
+  // `TS2551`, `eslint(no-unused-vars)`, `no-debugger` — whatever the tool
+  // calls the kind of finding; `""` when the format carries none.
+  readonly code: string;
+  // The first line of the message.
+  readonly message: string;
+};
+
+export type ReportFormat = "tsc" | "eslint" | "oxlint" | "regex";
+
+export type ParseReportOptions = {
+  // Absolute paths in the report are made relative to this.
+  readonly repoRoot: string;
+  // `regex` only: a pattern with named groups `file` and `line`, and
+  // optionally `column`, `code` and `message`; one diagnostic per line that
+  // matches, positions one-based as tools print them.
+  readonly pattern?: string | undefined;
+};
+
+const relativeTo = (repoRoot: string, file: string): string => {
+  const slashed = file.replaceAll("\\", "/");
+  const root = repoRoot.replaceAll("\\", "/").replace(/\/$/, "");
+  const relative =
+    slashed === root
+      ? ""
+      : slashed.startsWith(`${root}/`)
+        ? slashed.slice(root.length + 1)
+        : slashed;
+  return relative.replace(/^\.\//, "");
+};
+
+const oneBased = (value: string | undefined, fallback = 1): number => {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed >= 1 ? parsed - 1 : fallback - 1;
+};
+
+const firstLine = (message: string): string => message.split(/\r?\n/, 1)[0]?.trim() ?? "";
+
+// `src/a.ts(12,5): error TS2551: Property 'x' does not exist…`, one per
+// line, with the continuation lines tsc indents beneath a message ignored —
+// the first line is the message.
+const TSC_LINE = /^(.+?)\((\d+),(\d+)\): error (TS\d+): (.*)$/;
+
+const parseTsc = (text: string, options: ParseReportOptions): ReadonlyArray<Diagnostic> => {
+  const found: Array<Diagnostic> = [];
+  for (const line of text.split(/\r?\n/)) {
+    const match = TSC_LINE.exec(line);
+    if (match === null) continue;
+    const [, file = "", row, column, code = "", message = ""] = match;
+    found.push({
+      file: relativeTo(options.repoRoot, file),
+      line: oneBased(row),
+      column: oneBased(column),
+      code,
+      message: firstLine(message),
+    });
+  }
+  return found;
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const asString = (value: unknown): string => (typeof value === "string" ? value : "");
+const asNumber = (value: unknown): number | undefined =>
+  typeof value === "number" && Number.isFinite(value) ? value : undefined;
+
+const parseJson = (text: string, format: string): unknown => {
+  try {
+    return JSON.parse(text);
+  } catch (cause) {
+    throw new Error(`a ${format} report is JSON, and this one does not parse: ${String(cause)}`);
+  }
+};
+
+// `eslint --format json`: one object per file with its messages. A message
+// with no `ruleId` (a parse error) carries the code `""`.
+const parseEslint = (text: string, options: ParseReportOptions): ReadonlyArray<Diagnostic> => {
+  const parsed = parseJson(text, "eslint");
+  if (!Array.isArray(parsed)) throw new Error("an eslint report is a JSON array of files");
+  const found: Array<Diagnostic> = [];
+  for (const entry of parsed) {
+    if (!isRecord(entry) || !Array.isArray(entry.messages)) continue;
+    const file = relativeTo(options.repoRoot, asString(entry.filePath));
+    for (const message of entry.messages) {
+      if (!isRecord(message)) continue;
+      found.push({
+        file,
+        line: (asNumber(message.line) ?? 1) - 1,
+        column: (asNumber(message.column) ?? 1) - 1,
+        code: asString(message.ruleId),
+        message: firstLine(asString(message.message)),
+      });
+    }
+  }
+  return found;
+};
+
+// `oxlint --format json`: `{ diagnostics: [{ filename, code, message,
+// labels: [{ span: { line, column } }] }] }`, positions one-based.
+const parseOxlint = (text: string, options: ParseReportOptions): ReadonlyArray<Diagnostic> => {
+  const parsed = parseJson(text, "oxlint");
+  if (!isRecord(parsed) || !Array.isArray(parsed.diagnostics)) {
+    throw new Error("an oxlint report is a JSON object with a `diagnostics` array");
+  }
+  const found: Array<Diagnostic> = [];
+  for (const entry of parsed.diagnostics) {
+    if (!isRecord(entry)) continue;
+    const labels: ReadonlyArray<unknown> = Array.isArray(entry.labels) ? entry.labels : [];
+    const label: unknown = labels[0];
+    const span = isRecord(label) && isRecord(label.span) ? label.span : {};
+    found.push({
+      file: relativeTo(options.repoRoot, asString(entry.filename)),
+      line: (asNumber(span.line) ?? 1) - 1,
+      column: (asNumber(span.column) ?? 1) - 1,
+      code: asString(entry.code),
+      message: firstLine(asString(entry.message)),
+    });
+  }
+  return found;
+};
+
+const parseRegex = (text: string, options: ParseReportOptions): ReadonlyArray<Diagnostic> => {
+  if (options.pattern === undefined) {
+    throw new Error("a `regex` report needs a `pattern` with named groups `file` and `line`");
+  }
+  const pattern = new RegExp(options.pattern);
+  const found: Array<Diagnostic> = [];
+  for (const line of text.split(/\r?\n/)) {
+    const match = pattern.exec(line);
+    if (match === null) continue;
+    const groups = match.groups ?? {};
+    if (groups.file === undefined) continue;
+    found.push({
+      file: relativeTo(options.repoRoot, groups.file),
+      line: oneBased(groups.line),
+      column: oneBased(groups.column),
+      code: groups.code ?? "",
+      message: firstLine(groups.message ?? ""),
+    });
+  }
+  return found;
+};
+
+export const parseReport = (
+  format: ReportFormat,
+  text: string,
+  options: ParseReportOptions,
+): ReadonlyArray<Diagnostic> => {
+  switch (format) {
+    case "tsc":
+      return parseTsc(text, options);
+    case "eslint":
+      return parseEslint(text, options);
+    case "oxlint":
+      return parseOxlint(text, options);
+    case "regex":
+      return parseRegex(text, options);
+  }
+};
+
+// One report from several outputs. A tool that takes one project at a time
+// is run once per project, and a project's program includes the files of
+// the projects it references, so one diagnostic is printed under several
+// runs; it is one diagnostic. Kept once, at its first appearance, when
+// identical in file, position, code and message.
+export const uniqueDiagnostics = (diagnostics: Iterable<Diagnostic>): ReadonlyArray<Diagnostic> => {
+  const seen = new Set<string>();
+  const kept: Array<Diagnostic> = [];
+  for (const one of diagnostics) {
+    const key = JSON.stringify([one.file, one.line, one.column, one.code, one.message]);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    kept.push(one);
+  }
+  return kept;
+};
+
+// The diagnostics indexed by file, which is how a per-file evaluator asks
+// for them.
+export const indexByFile = (
+  diagnostics: Iterable<Diagnostic>,
+): ReadonlyMap<string, ReadonlyArray<Diagnostic>> => {
+  const byFile = new Map<string, Array<Diagnostic>>();
+  for (const one of diagnostics) {
+    const found = byFile.get(one.file);
+    if (found === undefined) byFile.set(one.file, [one]);
+    else found.push(one);
+  }
+  return byFile;
+};

package/src/domain/snapshot.ts

@@ -0,0 +1,302 @@
+import * as Schema from "effect/Schema";
+
+import type { ViolationKind } from "./violation.js";
+
+// The conformance snapshot: one JSON document per run saying how far the
+// tree is from the manifest. `architecture conformance --json` emits it, a
+// pull-request check compares two of them, an agent reads one before it
+// edits, and a service that keeps history stores them — so it is a wire
+// format, defined here with a schema before anything consumes it, and
+// versioned so a document that grows it can say which one it grew.
+//
+// Three things it says that `check` does not: the residue (what no family
+// reaches), the slack (what the allowlists permit and nothing uses), and the
+// violations ordered by how much of the graph each fix drags along. Every
+// entry that names a violation names it by its line-independent fingerprint,
+// which is what lets one be tracked across commits.
+
+export const SNAPSHOT_SCHEMA_ID =
+  "https://dataquail.github.io/goodbones/schema/conformance.schema.json";
+
+export const SNAPSHOT_VERSION = 1;
+
+const describe = <S extends Schema.Top>(schema: S, description: string) =>
+  schema.annotate({ description });
+
+const COVERAGE_FAMILIES = ["imports", "structure", "members", "surface", "graph"] as const;
+
+// The kinds `Violation` carries, spelled here as a schema; the `satisfies`
+// below keeps the two lists one.
+const VIOLATION_KINDS = [
+  "import",
+  "export",
+  "structure",
+  "member",
+  "surface",
+  "graph",
+  "campaign",
+] as const satisfies ReadonlyArray<ViolationKind>;
+
+const Path = describe(Schema.String, "Repo-relative, with forward slashes.");
+
+const FamilyCoverage = Schema.Struct({
+  covered: describe(Schema.Finite, "Files this family reaches."),
+  total: describe(Schema.Finite, "Files walked."),
+  floor: Schema.optionalKey(
+    describe(
+      Schema.Finite,
+      "The fraction the manifest's `limits.coverage` states for this family, when it states one.",
+    ),
+  ),
+});
+
+export const CONFORMANCE_MEASURES = ["residue", "vacant", "slack", "concentration"] as const;
+
+export type ConformanceMeasure = (typeof CONFORMANCE_MEASURES)[number];
+
+// One conformance measure as `check` holds it: the count, and the ceiling
+// the manifest's `limits.conformance` states for it, when it states one.
+const MeasureCount = Schema.Struct({
+  count: describe(Schema.Finite, "What the measure counts today."),
+  ceiling: Schema.optionalKey(
+    describe(
+      Schema.Finite,
+      "The count the manifest's `limits.conformance` states for this measure, when it states one.",
+    ),
+  ),
+});
+
+export const SnapshotViolation = Schema.Struct({
+  fingerprint: describe(
+    Schema.String,
+    "kind|rule|file|subject — line-independent, so it survives edits to the file it names; the baseline's key.",
+  ),
+  kind: Schema.Literals(VIOLATION_KINDS),
+  ruleName: describe(Schema.String, "The manifest node path the rule was lowered from."),
+  file: Path,
+  subject: describe(
+    Schema.NullOr(Schema.String),
+    "The other end of the violated relationship — the resolved target, the restricted symbol, the missing sibling — or null when the file alone is the violation.",
+  ),
+  message: Schema.String,
+  baselined: describe(Schema.Boolean, "Carried by the baseline, so `check` does not fail on it."),
+  ledgered: describe(
+    Schema.Boolean,
+    "For a campaign hit: carried by the campaign's ledger, so `check` does not fail on it.",
+  ),
+});
+
+const AllowanceKind = describe(
+  Schema.Literals(["allow", "external"]),
+  "`allow` is a path glob under `imports.allow`; `external` a package name under `imports.external`.",
+);
+
+const Entry = describe(Schema.String, "The entry as written, after alias expansion.");
+
+export const SnapshotSlack = Schema.Struct({
+  node: describe(
+    Schema.String,
+    "The manifest node that wrote the entry — or, when `fragment` is set, the `defs` fragment it was written in.",
+  ),
+  kind: AllowanceKind,
+  entry: Entry,
+  fragment: Schema.optionalKey(
+    describe(
+      Schema.String,
+      "Present when the entry arrived through `use`. The nodes that referenced the fragment wrote one word, so the entry is reported once, against the fragment, rather than once per node.",
+    ),
+  ),
+  of: Schema.optionalKey(
+    describe(
+      Schema.Finite,
+      "With `fragment`: how many non-vacant nodes were granted the entry through it. None of them uses it.",
+    ),
+  ),
+});
+
+export const SnapshotConcentration = Schema.Struct({
+  fragment: describe(Schema.String, "The `defs` fragment the entry was written in."),
+  kind: AllowanceKind,
+  entry: Entry,
+  usedAt: describe(Schema.Finite, "Nodes granted the entry through the fragment that use it."),
+  of: describe(Schema.Finite, "Non-vacant nodes granted the entry through the fragment."),
+});
+
+export const SnapshotVacancy = Schema.Struct({
+  node: describe(Schema.String, "The manifest node."),
+  allowances: describe(
+    Schema.Finite,
+    "Distinct entries the node wrote, `allow` and `external` together.",
+  ),
+});
+
+// One campaign's burn-down: what its ledger says, and what the clock says
+// about it. Every count is over ledger entries, which are hits by fingerprint.
+export const SnapshotCampaign = Schema.Struct({
+  id: describe(Schema.String, "The campaign's id; its ledger is `<ledger>/<id>.json`."),
+  title: Schema.optionalKey(describe(Schema.String, "The campaign's title, when it states one.")),
+  owner: Schema.optionalKey(
+    describe(Schema.String, "Who is running the campaign, as the manifest names them."),
+  ),
+  initial: describe(Schema.Finite, "Entries the day the ledger was written."),
+  allowed: describe(
+    Schema.Finite,
+    "Entries added since by `campaigns allow`, each with a regression record.",
+  ),
+  count: describe(Schema.Finite, "Entries in the ledger now."),
+  fixed: describe(
+    Schema.Finite,
+    "Entries removed by `campaigns prune` since the ledger was written.",
+  ),
+  progress: describe(
+    Schema.Finite,
+    "`1 - count / (initial + allowed)`: how much of everything ever ledgered has been paid down.",
+  ),
+  lastProgress: describe(
+    Schema.String,
+    "When an entry last left the ledger, ISO 8601 — the stall clock's reading.",
+  ),
+  regressions: describe(Schema.Finite, "How many times the count was allowed to go up."),
+  stalled: describe(
+    Schema.Boolean,
+    "Entries remain and `lastProgress` is older than the campaign's `staleAfter`.",
+  ),
+  complete: describe(Schema.Boolean, "No entries remain."),
+  onComplete: describe(
+    Schema.Literals(["keep", "remove"]),
+    "What the manifest asks once complete: keep the campaign as a guard, or remove it.",
+  ),
+  ledgered: describe(
+    Schema.Boolean,
+    "Whether a ledger exists. A campaign with none has been declared and not yet initialised.",
+  ),
+});
+
+export const Snapshot = Schema.Struct({
+  version: describe(Schema.Literal(SNAPSHOT_VERSION), "The shape of this document."),
+  manifest: describe(
+    Schema.Struct({
+      path: describe(
+        Path,
+        "The file the policy was read from — the root file, when split with `include`.",
+      ),
+      sha256: describe(
+        Schema.String,
+        "A hash of that file's bytes, so two snapshots can say whether the policy changed between them.",
+      ),
+    }),
+    "The policy this snapshot was taken against — the repository's own, or the one `--against` named.",
+  ),
+  roots: describe(Schema.Array(Path), "The directories walked."),
+  files: describe(Schema.Finite, "Files walked."),
+  ok: describe(
+    Schema.Boolean,
+    "What `check` would exit with: true when no reportable violation, unresolved import, stale baseline entry or coverage shortfall exists.",
+  ),
+  coverage: describe(
+    Schema.Struct(
+      Object.fromEntries(COVERAGE_FAMILIES.map((family) => [family, FamilyCoverage])) as Record<
+        (typeof COVERAGE_FAMILIES)[number],
+        typeof FamilyCoverage
+      >,
+    ),
+    "Per family, how many walked files it reaches. Structure counts enumerated folders only.",
+  ),
+  conformance: describe(
+    Schema.Struct(
+      Object.fromEntries(CONFORMANCE_MEASURES.map((measure) => [measure, MeasureCount])) as Record<
+        ConformanceMeasure,
+        typeof MeasureCount
+      >,
+    ),
+    "Per measure, the count `check` holds to the manifest's `limits.conformance`: residue files, vacant nodes, slack allowances, and fragment entries used at fewer than half the nodes granted them. The lists below name what each counts.",
+  ),
+  residue: describe(
+    Schema.Struct({
+      files: describe(Schema.Array(Path), "Files no family reaches, sorted."),
+      folders: describe(
+        Schema.Array(Path),
+        "Folders every walked file of which is residue, each the topmost such folder.",
+      ),
+    }),
+    "What the policy has nothing to say about. A file in an open folder under no allowlist is claimed, not policed, and counts.",
+  ),
+  vacant: describe(
+    Schema.Array(SnapshotVacancy),
+    "Nodes that state an import allowlist and select no walked file, in manifest order. Every allowance on one is unused by construction, so none is counted as slack; the node is a tier declared ahead of its first file, or a pattern that no longer matches. Residue is files no node reaches; this is nodes no file reaches.",
+  ),
+  violations: describe(
+    Schema.Array(SnapshotViolation),
+    "Every finding, baselined ones included, ordered so the ones cheapest to fix come first: by the height of the violated target in the import graph, leaves first.",
+  ),
+  unresolved: describe(
+    Schema.Array(Schema.Struct({ file: Path, specifier: Schema.String, detail: Schema.String })),
+    "Imports the resolver could not turn into a file. Every rule about one enforces nothing.",
+  ),
+  stale: describe(Schema.Array(Schema.String), "Baseline entries the code no longer produces."),
+  baseline: describe(
+    Schema.Struct({
+      size: describe(Schema.Finite, "Entries in the baseline file."),
+    }),
+    "The debt the policy is carrying. The ratchet: it may only shrink.",
+  ),
+  cycles: describe(
+    Schema.Finite,
+    "Strongly connected components of more than one file, or a file importing itself, anywhere in the walked graph — in a cycles rule's scope or not.",
+  ),
+  slack: describe(
+    Schema.Array(SnapshotSlack),
+    "Allowances no observed import uses, in manifest order, vacant nodes excluded. A manifest inferred from the tree has none on the day it is written; every entry here is permission nothing needs. An entry that arrived through `use` is reported once, against the fragment, and only when no node granted it uses it.",
+  ),
+  concentration: describe(
+    Schema.Array(SnapshotConcentration),
+    "Fragment entries used at some of the nodes granted them and not the rest. Not slack — the fragment's line is needed somewhere — but a per-file permission written as a many-node allowance, which is what an allowlist widened to make one build green looks like.",
+  ),
+  adoption: describe(
+    Schema.Struct({
+      unrestricted: describe(Schema.Array(Schema.String), "Nodes that say `unrestricted: true`."),
+      partial: describe(Schema.Array(Schema.String), "Nodes that say `partial: true`."),
+    }),
+    'The tiers that said "not tightened yet", by name; `limits` caps how many may.',
+  ),
+  campaigns: describe(
+    Schema.Array(SnapshotCampaign),
+    "Every campaign the manifest declares, in manifest order, with its burn-down. Campaign hits are not counted in `coverage` or `residue`: a campaign is scoped by construction.",
+  ),
+});
+
+export type Snapshot = typeof Snapshot.Type;
+export type SnapshotViolation = typeof SnapshotViolation.Type;
+export type SnapshotSlack = typeof SnapshotSlack.Type;
+export type SnapshotConcentration = typeof SnapshotConcentration.Type;
+export type SnapshotVacancy = typeof SnapshotVacancy.Type;
+export type SnapshotCampaign = typeof SnapshotCampaign.Type;
+
+// Decodes a document some other run wrote — the base of a pull request, a
+// stored one — refusing a key the shape does not declare, so a consumer never
+// reads a field that a later version renamed.
+export const decodeSnapshot = Schema.decodeUnknownResult(Snapshot, {
+  errors: "all",
+  onExcessProperty: "error",
+});
+
+type JsonValue = string | number | boolean | null | JsonObject | ReadonlyArray<JsonValue>;
+type JsonObject = { readonly [key: string]: JsonValue };
+
+// The document's shape as a JSON Schema, generated from the same codec, so
+// the two cannot disagree. Published beside the manifest's.
+export const snapshotJsonSchema = (): JsonObject => {
+  const generated = Schema.toJsonSchemaDocument(Snapshot) as unknown as {
+    readonly schema: JsonObject;
+    readonly definitions: JsonObject;
+  };
+  return {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: SNAPSHOT_SCHEMA_ID,
+    title: "Conformance snapshot",
+    description:
+      "How far a repository's tree is from its architecture manifest, as `architecture conformance --json` reports it. See https://dataquail.github.io/goodbones/architecture-rules/enforcement/conformance/.",
+    ...generated.schema,
+    ...(Object.keys(generated.definitions).length === 0 ? {} : { $defs: generated.definitions }),
+  };
+};

package/src/domain/violation.ts

@@ -1,4 +1,7 @@
-export type ViolationKind = "import" | "export" | "structure" | "member" | "surface" | "graph";
+// `campaign` is the one kind whose entries live in a ledger rather than the
+// baseline: a hit is debt a campaign is paying down, not a rule being broken.
+export type ViolationKind =
+  "import" | "export" | "structure" | "member" | "surface" | "graph" | "campaign";
 
 export type Violation = {
   readonly kind: ViolationKind;