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

package/src/core/ledger.ts

@@ -1,242 +0,0 @@
-import * as Result from "effect/Result";
-import * as Schema from "effect/Schema";
-
-import type { CampaignUnit } from "../domain/architecture-config.js";
-import type { Violation } from "../domain/violation.js";
-
-// A campaign's ledger: every place the pattern still occurs, and the record of
-// every time the count was allowed to go up. It is the baseline's cousin and
-// not the baseline — same fingerprint, different file, different semantics.
-//
-//   - One file per campaign, so two pull requests migrating different
-//     components never conflict, and finishing a campaign is deleting its file.
-//   - Growth is only ever recorded, never silent. `prune` only removes;
-//     `allow` is the one way an entry is added, and it always appends a
-//     regression with a reason, a timestamp and an author.
-//   - The arithmetic is checked: `entries.length === initial + Σ delta − fixed`.
-//     A hand-added entry with no regression record fails the build, with no
-//     git history in the loop.
-//   - A fixed entry is stale, and `check` fails on it as it fails on a stale
-//     baseline entry, so progress lands as a visible diff.
-
-const Regression = Schema.Struct({
-  at: Schema.String,
-  by: Schema.String,
-  delta: Schema.Finite,
-  reason: Schema.String,
-  entries: Schema.Array(Schema.String),
-});
-
-export const Ledger = Schema.Struct({
-  version: Schema.Literal(1),
-  id: Schema.String,
-  created: Schema.String,
-  // The count on the day the ledger was written.
-  initial: Schema.Finite,
-  // Entries removed by `prune` since.
-  fixed: Schema.Finite,
-  // When an entry last left the ledger — what the stall clock reads.
-  lastProgress: Schema.String,
-  regressions: Schema.Array(Regression),
-  // `file` or `file#subject`, deduplicated and sorted.
-  entries: Schema.Array(Schema.String),
-});
-
-export type Ledger = typeof Ledger.Type;
-export type Regression = typeof Regression.Type;
-
-const decode = Schema.decodeUnknownResult(Ledger, { errors: "all", onExcessProperty: "error" });
-
-export const EMPTY_LEDGER = (id: string, now: number): Ledger => {
-  const at = new Date(now).toISOString();
-  return {
-    version: 1,
-    id,
-    created: at,
-    initial: 0,
-    fixed: 0,
-    lastProgress: at,
-    regressions: [],
-    entries: [],
-  };
-};
-
-// A malformed ledger is refused, unlike a malformed baseline, which reads as
-// empty: an empty baseline reports every violation, the safe direction, while
-// an empty ledger would report every hit as unrecorded growth and demand a
-// regression record for debt that was already counted.
-export const decodeLedger = (raw: unknown): Result.Result<Ledger, string> => {
-  const decoded = decode(raw);
-  return Result.isFailure(decoded)
-    ? Result.fail(String(decoded.failure.issue))
-    : Result.succeed(decoded.success);
-};
-
-export const serializeLedger = (ledger: Ledger): string => `${JSON.stringify(ledger, null, 2)}\n`;
-
-// A hit's entry: the file, and its subject when the campaign's unit has one.
-export const entryOf = (violation: Violation): string =>
-  violation.subject === null ? violation.file : `${violation.file}#${violation.subject}`;
-
-const allowedTotal = (ledger: Ledger): number =>
-  ledger.initial + ledger.regressions.reduce((sum, one) => sum + one.delta, 0);
-
-export const ledgerArithmeticHolds = (ledger: Ledger): boolean =>
-  ledger.entries.length === allowedTotal(ledger) - ledger.fixed;
-
-// A `match` entry is `file#anchor#hash`; an edit inside the anchored
-// declaration changes the hash and nothing else, and is the same entry.
-const anchorOf = (entry: string): string => entry.slice(0, entry.lastIndexOf("#"));
-
-export type Reconciliation = {
-  // Hits the ledger already carries, exactly or by anchor.
-  readonly ledgered: ReadonlyArray<Violation>;
-  // Hits the ledger does not carry: unrecorded growth.
-  readonly unrecorded: ReadonlyArray<Violation>;
-  // Entries no hit produces: fixed, and waiting to be pruned.
-  readonly stale: ReadonlyArray<string>;
-  // Entries whose hash moved under a still-present anchor, with what they
-  // read now. `prune` rewrites them; they count as neither fixed nor new.
-  readonly drifted: ReadonlyArray<{ readonly from: string; readonly to: string }>;
-};
-
-export const reconcile = (
-  ledger: Ledger,
-  hits: Iterable<Violation>,
-  unit: CampaignUnit,
-): Reconciliation => {
-  const entries = new Set(ledger.entries);
-  const ledgered: Array<Violation> = [];
-  const unmatched: Array<Violation> = [];
-  const current = new Set<string>();
-  for (const hit of hits) {
-    const entry = entryOf(hit);
-    current.add(entry);
-    if (entries.has(entry)) ledgered.push(hit);
-    else unmatched.push(hit);
-  }
-  let stale = ledger.entries.filter((entry) => !current.has(entry));
-  const drifted: Array<{ from: string; to: string }> = [];
-  const unrecorded: Array<Violation> = [];
-
-  if (unit === "match") {
-    // Pair each stale entry with an unmatched hit under the same anchor, in
-    // order, so a declaration with two edited matches keeps two entries.
-    const byAnchor = new Map<string, Array<string>>();
-    for (const entry of stale) {
-      const anchor = anchorOf(entry);
-      byAnchor.set(anchor, [...(byAnchor.get(anchor) ?? []), entry]);
-    }
-    const paired = new Set<string>();
-    for (const hit of unmatched) {
-      const entry = entryOf(hit);
-      const candidates = byAnchor.get(anchorOf(entry));
-      const from = candidates?.shift();
-      if (from === undefined) {
-        unrecorded.push(hit);
-        continue;
-      }
-      paired.add(from);
-      drifted.push({ from, to: entry });
-      ledgered.push(hit);
-    }
-    stale = stale.filter((entry) => !paired.has(entry));
-  } else {
-    for (const hit of unmatched) unrecorded.push(hit);
-  }
-
-  return { ledgered, unrecorded, stale, drifted };
-};
-
-export const staleEntriesOf = (
-  ledger: Ledger,
-  hits: Iterable<Violation>,
-  unit: CampaignUnit,
-): ReadonlyArray<string> => reconcile(ledger, hits, unit).stale;
-
-export const newEntriesOf = (
-  ledger: Ledger,
-  hits: Iterable<Violation>,
-  unit: CampaignUnit,
-): ReadonlyArray<string> => reconcile(ledger, hits, unit).unrecorded.map(entryOf);
-
-const sorted = (entries: Iterable<string>): ReadonlyArray<string> => [...new Set(entries)].sort();
-
-// A first ledger: every hit is an entry, and the count is the `initial`.
-export const ledgerOf = (id: string, hits: Iterable<Violation>, now: number): Ledger => {
-  const entries = sorted([...hits].map(entryOf));
-  return { ...EMPTY_LEDGER(id, now), initial: entries.length, entries };
-};
-
-// `prune`: the stale entries leave, `fixed` rises by as many, and
-// `lastProgress` moves — only when something left. A drifted entry is
-// rewritten in place and counts as neither.
-export const pruned = (
-  ledger: Ledger,
-  hits: Iterable<Violation>,
-  unit: CampaignUnit,
-  now: number,
-): Ledger => {
-  const { drifted, stale } = reconcile(ledger, hits, unit);
-  const rewritten = new Map(drifted.map((one) => [one.from, one.to]));
-  const gone = new Set(stale);
-  const entries = sorted(
-    ledger.entries
-      .filter((entry) => !gone.has(entry))
-      .map((entry) => rewritten.get(entry) ?? entry),
-  );
-  return {
-    ...ledger,
-    fixed: ledger.fixed + stale.length,
-    lastProgress: stale.length > 0 ? new Date(now).toISOString() : ledger.lastProgress,
-    entries,
-  };
-};
-
-export type RegressionRecord = {
-  readonly at: number;
-  readonly by: string;
-  readonly reason: string;
-};
-
-// `allow`: the entries join the ledger, and a regression records that they
-// did. The delta is what was actually added — an entry already present is
-// not growth.
-export const allowed = (
-  ledger: Ledger,
-  entries: Iterable<string>,
-  record: RegressionRecord,
-): Ledger => {
-  const present = new Set(ledger.entries);
-  const added = sorted([...entries].filter((entry) => !present.has(entry)));
-  if (added.length === 0) return ledger;
-  return {
-    ...ledger,
-    regressions: [
-      ...ledger.regressions,
-      {
-        at: new Date(record.at).toISOString(),
-        by: record.by,
-        delta: added.length,
-        reason: record.reason,
-        entries: added,
-      },
-    ],
-    entries: sorted([...ledger.entries, ...added]),
-  };
-};
-
-// `1 − count / (initial + Σ delta)`: how much of everything the campaign was
-// ever asked to pay down has been paid.
-export const progressOf = (ledger: Ledger): number => {
-  const total = allowedTotal(ledger);
-  return total === 0 ? 1 : 1 - ledger.entries.length / total;
-};
-
-export const isComplete = (ledger: Ledger): boolean => ledger.entries.length === 0;
-
-export const isStalled = (
-  rule: { readonly staleAfter: number },
-  ledger: Ledger,
-  now: number,
-): boolean => !isComplete(ledger) && now - Date.parse(ledger.lastProgress) > rule.staleAfter;

package/src/domain/report.ts

@@ -1,203 +0,0 @@
-// 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/infrastructure/campaign-functions.ts

@@ -1,98 +0,0 @@
-import * as path from "node:path";
-import { pathToFileURL } from "node:url";
-
-import { ConfigInvalid } from "../domain/architecture-error.js";
-import type { CampaignPredicate } from "../ports/campaign-predicate.js";
-
-// A campaign's `fn` term names a predicate function as `module#export`,
-// resolved relative to the root manifest. Importing it touches the module
-// loader, which is why this lives in infrastructure and both hosts call it
-// before `loadPolicy`: the core receives the functions as a map and never
-// imports anything.
-//
-// A `.mjs` manifest may write the function itself in place of the string.
-// It is lifted out here, keyed by a synthesized name, and the manifest handed
-// back with the string in its place — so the schema, which decodes a data
-// file and a module alike, sees one shape. The whole value is walked, not
-// only `campaigns`, so a term written in a `defs` fragment is found too.
-
-export type LoadedCampaignFunctions = {
-  readonly functions: ReadonlyMap<string, CampaignPredicate>;
-  // The manifest with every function value replaced by its synthesized name.
-  readonly manifest: unknown;
-};
-
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === "object" && value !== null && !Array.isArray(value);
-
-const REFERENCE = /^(.+)#([A-Za-z_$][\w$]*)$/;
-
-// A `fn` term is an object whose one key is `fn`.
-const isFnTerm = (value: Record<string, unknown>): boolean =>
-  "fn" in value && Object.keys(value).length === 1;
-
-export const loadCampaignFunctions = async (
-  manifestPath: string,
-  rawManifest: unknown,
-): Promise<LoadedCampaignFunctions> => {
-  const functions = new Map<string, CampaignPredicate>();
-  const root = path.dirname(manifestPath);
-  const refuse = (detail: string): never => {
-    throw new ConfigInvalid({ configPath: manifestPath, detail });
-  };
-
-  const imported = async (reference: string): Promise<void> => {
-    if (functions.has(reference)) return;
-    const parsed = REFERENCE.exec(reference);
-    if (parsed === null) {
-      return refuse(
-        `the \`fn\` term ${JSON.stringify(reference)} is not \`module#export\`: name the ` +
-          `module (relative to the manifest) and the export, joined by \`#\`.`,
-      );
-    }
-    const [, module = "", exportName = ""] = parsed;
-    const at = path.resolve(root, module);
-    let loaded: unknown;
-    try {
-      loaded = await import(pathToFileURL(at).href);
-    } catch (cause) {
-      return refuse(
-        `the \`fn\` term ${JSON.stringify(reference)} names a module that does not load: ${String(cause)}`,
-      );
-    }
-    const found = isRecord(loaded) ? loaded[exportName] : undefined;
-    if (typeof found !== "function") {
-      return refuse(
-        `the \`fn\` term ${JSON.stringify(reference)} names an export that is not a function ` +
-          `(${found === undefined ? "absent" : typeof found}).`,
-      );
-    }
-    functions.set(reference, found as CampaignPredicate);
-  };
-
-  let synthesized = 0;
-  const lift = async (value: unknown): Promise<unknown> => {
-    if (Array.isArray(value)) {
-      const items: Array<unknown> = [];
-      for (const item of value) items.push(await lift(item));
-      return items;
-    }
-    if (!isRecord(value)) return value;
-    if (isFnTerm(value)) {
-      const fn = value.fn;
-      if (typeof fn === "function") {
-        synthesized += 1;
-        const name = `<manifest>#fn${String(synthesized)}`;
-        functions.set(name, fn as CampaignPredicate);
-        return { fn: name };
-      }
-      if (typeof fn === "string") await imported(fn);
-      return value;
-    }
-    const rebuilt: Record<string, unknown> = {};
-    for (const [key, entry] of Object.entries(value)) rebuilt[key] = await lift(entry);
-    return rebuilt;
-  };
-
-  return { functions, manifest: await lift(rawManifest) };
-};

package/src/infrastructure/report-source-fake.ts

@@ -1,10 +0,0 @@
-import type { Diagnostic } from "../domain/report.js";
-import type { ReportSource } from "../ports/report-source.js";
-
-// Keyed by file: a test states which diagnostics another tool reported on
-// which file, and never runs the tool. Every spec is answered alike.
-export const makeReportSourceFake = (
-  staged: Readonly<Record<string, ReadonlyArray<Omit<Diagnostic, "file">>>>,
-): ReportSource => ({
-  diagnosticsOf: (_spec, file) => (staged[file] ?? []).map((one) => ({ ...one, file })),
-});