@goodbones/core 0.1.0-beta.6 → 0.1.0-beta.8

package/src/domain/snapshot.ts

@@ -34,6 +34,7 @@ const VIOLATION_KINDS = [
   "member",
   "surface",
   "graph",
+  "campaign",
 ] as const satisfies ReadonlyArray<ViolationKind>;
 
 const Path = describe(Schema.String, "Repo-relative, with forward slashes.");
@@ -63,6 +64,10 @@ export const SnapshotViolation = Schema.Struct({
   ),
   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(
@@ -109,6 +114,48 @@ export const SnapshotVacancy = Schema.Struct({
   ),
 });
 
+// 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(
@@ -187,6 +234,10 @@ export const Snapshot = Schema.Struct({
     }),
     '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;
@@ -194,6 +245,7 @@ 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

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;

package/src/index.ts

@@ -14,6 +14,24 @@ export {
   staleEntriesOf,
   unbaselined,
 } from "./core/baseline.js";
+export {
+  type CampaignHit,
+  type CampaignInput,
+  campaignsFailingTheirProbe,
+  campaignsSelecting,
+  compileCampaignRule,
+  compileCampaignRules,
+  type CompiledCampaign,
+  type CompiledDetector,
+  evaluateCampaign,
+  evaluateCampaigns,
+  explainCampaign,
+  type FailedProbe,
+  leafTermsOf,
+  matchKeyOf,
+  probeInputOf,
+  type TermAnswer,
+} from "./core/campaigns.js";
 export {
   type Coverage,
   type CoverageFamily,
@@ -64,6 +82,27 @@ export {
   rulesSelecting,
   type SelectedRule,
 } from "./core/imports.js";
+export {
+  allowed,
+  decodeLedger,
+  EMPTY_LEDGER,
+  entryOf,
+  isComplete,
+  isStalled,
+  type Ledger,
+  ledgerArithmeticHolds,
+  ledgerOf,
+  Ledger as LedgerSchema,
+  newEntriesOf,
+  progressOf,
+  pruned,
+  reconcile,
+  type Reconciliation,
+  type Regression,
+  type RegressionRecord,
+  serializeLedger,
+  staleEntriesOf as staleLedgerEntriesOf,
+} from "./core/ledger.js";
 export {
   type CompiledMemberRule,
   compileMemberRules,
@@ -96,7 +135,11 @@ export {
 export {
   type Allowance,
   type BindingKind,
+  type CampaignProbe,
+  type CampaignRule,
+  type CampaignUnit,
   type DeclarationKind,
+  type Detector,
   type ExportFix,
   type ExportRule,
   type GraphConfig,
@@ -108,6 +151,7 @@ export {
   type ImportRule,
   type MemberRule,
   type MemberSubject,
+  type ProbeDiagnostic,
   type ResolveConfig,
   type ResolveScope,
   type StructureConfig,
@@ -131,11 +175,19 @@ export {
   type ManifestPosition,
   renderManifestPath,
 } from "./domain/manifest-location.js";
+export {
+  type Diagnostic,
+  indexByFile,
+  parseReport,
+  type ParseReportOptions,
+  type ReportFormat,
+} from "./domain/report.js";
 export {
   decodeSnapshot,
   type Snapshot,
   SNAPSHOT_SCHEMA_ID,
   SNAPSHOT_VERSION,
+  type SnapshotCampaign,
   type SnapshotConcentration,
   snapshotJsonSchema,
   Snapshot as SnapshotSchema,
@@ -149,6 +201,10 @@ export {
   type Violation,
   type ViolationKind,
 } from "./domain/violation.js";
+export {
+  loadCampaignFunctions,
+  type LoadedCampaignFunctions,
+} from "./infrastructure/campaign-functions.js";
 export { makeFileSystemLive } from "./infrastructure/file-system-live.js";
 export {
   findManifestFile,
@@ -163,6 +219,7 @@ export {
   type IncludeReader,
   type SourceDocument,
 } from "./infrastructure/manifest-include.js";
+export { makeReportSourceLive } from "./infrastructure/report-source-live.js";
 export {
   listPackageRoots,
   listSourceFiles,
@@ -204,13 +261,23 @@ export {
   manifestNodeJsonSchema,
 } from "./manifest/json-schema.js";
 export {
+  type CampaignSpec,
   type DecodedManifest,
   decodeManifest,
   type DecodeManifestOptions,
+  DEFAULT_LEDGER_DIR,
+  type DetectorSpec,
+  durationMs,
   type Manifest,
   type ManifestNode,
   Manifest as ManifestSchema,
 } from "./manifest/manifest.js";
+export {
+  type CampaignPredicate,
+  type CampaignPredicateInput,
+  type CampaignSubject,
+  type Range,
+} from "./ports/campaign-predicate.js";
 export { type FactExtractor } from "./ports/fact-extractor.js";
 export { type FileSystem } from "./ports/file-system.js";
 export { type Language } from "./ports/language.js";
@@ -219,3 +286,10 @@ export {
   type ModuleResolver,
   type ResolvedTarget,
 } from "./ports/module-resolver.js";
+export { NO_REPORTS, type ReportSource, type ReportSpec } from "./ports/report-source.js";
+export {
+  type Position,
+  type SyntaxMatch,
+  type SyntaxMatcher,
+  type SyntaxTree,
+} from "./ports/syntax-matcher.js";

package/src/infrastructure/campaign-functions.ts

@@ -0,0 +1,98 @@
+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

@@ -0,0 +1,10 @@
+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 })),
+});

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

@@ -0,0 +1,66 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import * as path from "node:path";
+
+import { type Diagnostic, indexByFile, parseReport } from "../domain/report.js";
+import type { ReportSource, ReportSpec } from "../ports/report-source.js";
+
+// The report source on this host: runs a `report` term's command from the
+// repository root, or reads the file it names, and parses the output once —
+// a report is about the whole repository, a campaign asks per file, and the
+// plugin asks for one file at a time across a whole lint run. Cached per
+// spec for the life of the process: the CLI is one process per `check`, and
+// oxlint's language server is one process per editor session, which sees the
+// report as of when it loaded the plugin. A report the build writes to a file
+// is the predictable form for the editor.
+//
+// A non-zero exit is not a failure — `tsc` exits 2 when there are errors,
+// which is the case the term exists for. A command that cannot be spawned,
+// or a file that is not there, is.
+
+const MAX_BUFFER = 256 * 1024 * 1024;
+
+const textOf = (repoRoot: string, spec: ReportSpec): string => {
+  if (spec.file !== undefined) {
+    const at = path.resolve(repoRoot, spec.file);
+    try {
+      return readFileSync(at, "utf8");
+    } catch (cause) {
+      throw new Error(
+        `the report file ${spec.file} cannot be read: ${String(cause)}. A \`report\` term's ` +
+          `\`file\` is written by an earlier step; run that first, or name a \`command\`.`,
+      );
+    }
+  }
+  const command = spec.command ?? "";
+  const run = spawnSync(command, {
+    cwd: repoRoot,
+    shell: true,
+    encoding: "utf8",
+    maxBuffer: MAX_BUFFER,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (run.error !== undefined) {
+    throw new Error(`the report command \`${command}\` could not be run: ${run.error.message}`);
+  }
+  return run.stdout;
+};
+
+const keyOf = (spec: ReportSpec): string => JSON.stringify(spec);
+
+export const makeReportSourceLive = (repoRoot: string): ReportSource => {
+  const cache = new Map<string, ReadonlyMap<string, ReadonlyArray<Diagnostic>>>();
+  return {
+    diagnosticsOf: (spec, file) => {
+      const key = keyOf(spec);
+      let indexed = cache.get(key);
+      if (indexed === undefined) {
+        indexed = indexByFile(
+          parseReport(spec.format, textOf(repoRoot, spec), { repoRoot, pattern: spec.pattern }),
+        );
+        cache.set(key, indexed);
+      }
+      return indexed.get(file) ?? [];
+    },
+  };
+};

package/src/infrastructure/syntax-matcher-fake.ts

@@ -0,0 +1,51 @@
+import type { SyntaxMatch, SyntaxMatcher } from "../ports/syntax-matcher.js";
+
+// One match as a test states it: the text, its captures as a plain object,
+// the anchor, and optionally a line — the rest of the range is filled in.
+// `rule` narrows the match to one rule (compared by its JSON), so a test
+// about two `syntax` terms can answer each differently; omit it to answer
+// every rule the same.
+export type StagedMatch = {
+  readonly text: string;
+  readonly captures?: Readonly<Record<string, string>>;
+  readonly anchor?: string | null;
+  readonly line?: number;
+  readonly rule?: unknown;
+};
+
+const ZERO = { line: 0, column: 0 };
+
+// Keyed by the source text, as the extractor fake is: a core test states
+// what a snippet's syntax yields and never the parse, which has its own
+// tests in the matcher package. A text not staged parses to no matches; a
+// file whose extension is not among `extensions` does not parse at all,
+// which is the shape of a language with no matcher.
+export const makeSyntaxMatcherFake = (
+  staged: Readonly<Record<string, ReadonlyArray<StagedMatch>>>,
+  extensions: ReadonlyArray<string> | null = null,
+): SyntaxMatcher => ({
+  parse: (file, text) => {
+    if (extensions !== null && !extensions.some((extension) => file.endsWith(extension))) {
+      return null;
+    }
+    const matches = staged[text] ?? [];
+    return {
+      // A staged match's line is what a position is anchored by.
+      anchorAt: (position) => matches.find((one) => one.line === position.line)?.anchor ?? null,
+      findAll: (rule) => {
+        const asked = JSON.stringify(rule);
+        return matches
+          .filter((one) => one.rule === undefined || JSON.stringify(one.rule) === asked)
+          .map((one): SyntaxMatch => ({
+            text: one.text,
+            captures: new Map(Object.entries(one.captures ?? {})),
+            range: {
+              start: one.line === undefined ? ZERO : { line: one.line, column: 0 },
+              end: one.line === undefined ? ZERO : { line: one.line, column: one.text.length },
+            },
+            anchor: one.anchor ?? null,
+          }));
+      },
+    };
+  },
+});