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

package/src/load/policy.ts

@@ -7,6 +7,13 @@ import {
   EMPTY_BASELINE,
   makeBaselineFilter,
 } from "../core/baseline.js";
+import {
+  type CampaignPredicate,
+  campaignsFailingTheirProbe,
+  compileCampaignRules,
+  type CompiledCampaign,
+  leafTermsOf,
+} from "../core/campaigns.js";
 import {
   type CompiledExportRule,
   compileExportRules,
@@ -22,6 +29,7 @@ import {
   compileImportRules,
   rulesFailingTheirProbe,
 } from "../core/imports.js";
+import { decodeLedger, type Ledger } from "../core/ledger.js";
 import {
   type CompiledMemberRule,
   compileMemberRules,
@@ -46,11 +54,13 @@ import {
 import type { SourceFacts } from "../domain/facts.js";
 import type { ManifestLocator } from "../domain/manifest-location.js";
 import { type LoweredRules, lowerManifest } from "../manifest/compile.js";
-import { decodeManifest, type Manifest } from "../manifest/manifest.js";
+import { decodeManifest, DEFAULT_LEDGER_DIR, type Manifest } from "../manifest/manifest.js";
 import type { FactExtractor } from "../ports/fact-extractor.js";
 import type { FileSystem } from "../ports/file-system.js";
 import type { Language } from "../ports/language.js";
 import type { ModuleResolver } from "../ports/module-resolver.js";
+import { NO_REPORTS, type ReportSource } from "../ports/report-source.js";
+import type { SyntaxMatcher } from "../ports/syntax-matcher.js";
 
 // A manifest, read by a host, turned into the policy both adapters evaluate.
 // Decoding, lowering, compiling and probing happen here, once, with whatever
@@ -70,6 +80,19 @@ export type LoadedPolicy = {
   readonly graph: CompiledGraph;
   readonly adoption: LoweredRules["adoption"];
   readonly structure: CompiledStructure;
+  // Evaluated by both hosts, one file at a time; the ledgers say which hits
+  // are already counted. A campaign with no ledger is one `campaigns init`
+  // has not been run for, and `check` says so.
+  readonly campaignRules: ReadonlyArray<CompiledCampaign>;
+  readonly ledgers: ReadonlyMap<string, Ledger>;
+  // Repo-relative; `<ledgerDir>/<id>.json` is a campaign's ledger.
+  readonly ledgerDir: string;
+  // The predicate functions the host imported for the `fn` terms.
+  readonly functions: ReadonlyMap<string, CampaignPredicate>;
+  // Answers the `report` terms: the host's live source, or nothing.
+  readonly reports: ReportSource;
+  // The clock the campaigns are judged by — stalls, timestamps.
+  readonly now: number;
   readonly fileSystem: FileSystem;
   // The language packs this policy is evaluated with. The walker takes its
   // extensions from them, and lowering the shape of its probes.
@@ -82,6 +105,9 @@ export type LoadedPolicy = {
   // Routes each file to the extractor of the language whose scope covers it.
   // The CLI reads every file through this; the plugin reads oxlint's tree.
   readonly extractor: FactExtractor;
+  // Routes each file to the syntax matcher of the language whose scope
+  // covers it; `parse` answers `null` for a file whose language has none.
+  readonly syntax: SyntaxMatcher;
   readonly ignoreUnresolved: ReadonlyArray<RegExp>;
   // Deprecation notices from reading the manifest. The host prints them once.
   readonly notices: ReadonlyArray<string>;
@@ -99,6 +125,15 @@ export type LoadPolicyInput = {
   readonly locate?: ManifestLocator | undefined;
   readonly languages: ReadonlyArray<Language>;
   readonly fileSystem: FileSystem;
+  // The predicate functions the manifest's `fn` terms name, imported by the
+  // host before loading — the core touches no module loader.
+  readonly functions?: ReadonlyMap<string, CampaignPredicate> | undefined;
+  // The host's report source, for the `report` terms. Absent, a term
+  // answers nothing — a policy with one is refused, since it would be a
+  // campaign that can never fire.
+  readonly reports?: ReportSource | undefined;
+  // For tests and for a CI that pins the clock; defaults to `Date.now()`.
+  readonly now?: number | undefined;
 };
 
 const NOTHING: SourceFacts = {
@@ -144,6 +179,20 @@ const routesOf = (
 const routeFor = (routes: ReadonlyArray<Route>, file: string): Route | undefined =>
   routes.find((route) => route.matches.test(file));
 
+const referencedFunctions = (detect: CompiledCampaign["detect"]): ReadonlyArray<string> => {
+  switch (detect.kind) {
+    case "all":
+    case "any":
+      return detect.terms.flatMap(referencedFunctions);
+    case "not":
+      return referencedFunctions(detect.term);
+    case "fn":
+      return [detect.name];
+    default:
+      return [];
+  }
+};
+
 // One resolver per scope, built by the scope's language, behind one port that
 // picks the scope by the importing file.
 const makeRouter = (
@@ -184,6 +233,58 @@ const makeRoutingExtractor = (routes: ReadonlyArray<Route>): FactExtractor => ({
     routeFor(routes, file)?.language.extractor.factsOf(file, text) ?? NOTHING,
 });
 
+// One matcher per scope, behind one port that picks the scope by the file. A
+// language without one parses nothing, which a `syntax` term reads as no
+// matches — and which the probe check below refuses for a campaign that
+// depends on it.
+const makeRoutingMatcher = (routes: ReadonlyArray<Route>): SyntaxMatcher => ({
+  parse: (file, text) => routeFor(routes, file)?.language.syntax?.parse(file, text) ?? null,
+});
+
+// The ledgers, read through the port. An absent file is a campaign with no
+// ledger yet; a malformed one is refused, since reading it as empty would
+// report every hit as unrecorded growth.
+const readLedgers = (
+  configPath: string,
+  fileSystem: FileSystem,
+  ledgerDir: string,
+  campaigns: ReadonlyArray<CompiledCampaign>,
+): Result.Result<ReadonlyMap<string, Ledger>, ConfigInvalid> => {
+  const ledgers = new Map<string, Ledger>();
+  for (const campaign of campaigns) {
+    const at = `${ledgerDir}/${campaign.id}.json`;
+    const text = fileSystem.readText(at);
+    if (text === null) continue;
+    let raw: unknown;
+    try {
+      raw = JSON.parse(text);
+    } catch (cause) {
+      return Result.fail(
+        new ConfigInvalid({ configPath, detail: `the ledger ${at} is not JSON: ${String(cause)}` }),
+      );
+    }
+    const decoded = decodeLedger(raw);
+    if (Result.isFailure(decoded)) {
+      return Result.fail(
+        new ConfigInvalid({
+          configPath,
+          detail: `the ledger ${at} does not decode:\n${decoded.failure}`,
+        }),
+      );
+    }
+    if (decoded.success.id !== campaign.id) {
+      return Result.fail(
+        new ConfigInvalid({
+          configPath,
+          detail: `the ledger ${at} says it belongs to "${decoded.success.id}", not "${campaign.id}".`,
+        }),
+      );
+    }
+    ledgers.set(campaign.id, decoded.success);
+  }
+  return Result.succeed(ledgers);
+};
+
 // The baseline is read through the port, so this tier touches no file itself.
 // An absent or unreadable one carries nothing, which is the safe direction:
 // every violation reports.
@@ -280,6 +381,67 @@ export const loadPolicy = (
   const structure = compileStructure(rules.structure);
   if (Result.isFailure(structure)) return Result.fail(structure.failure);
 
+  const campaignRules = compileCampaignRules(rules.campaigns);
+  if (Result.isFailure(campaignRules)) return Result.fail(campaignRules.failure);
+
+  // A `fn` term names a function the host was to import. One it did not is
+  // a term that would answer false for every file, and is refused.
+  const functions = input.functions ?? new Map<string, CampaignPredicate>();
+  const missing = campaignRules.success.flatMap((rule) =>
+    referencedFunctions(rule.detect).filter((name) => !functions.has(name)),
+  );
+  if (missing.length > 0) {
+    return Result.fail(
+      new ConfigInvalid({
+        configPath,
+        detail:
+          `these campaigns name a predicate function the host did not load: ` +
+          `${[...new Set(missing)].join(", ")}. A \`fn\` term is \`module#export\`, resolved ` +
+          `relative to the manifest, and the export must be a function.`,
+      }),
+    );
+  }
+
+  // A `report` term is answered by the host's source. Without one every
+  // such campaign would report nothing and look complete.
+  const reporting = campaignRules.success.filter((rule) =>
+    leafTermsOf(rule.detect).includes("report"),
+  );
+  if (input.reports === undefined && reporting.length > 0) {
+    return Result.fail(
+      new ConfigInvalid({
+        configPath,
+        detail:
+          `these campaigns hold a \`report\` term and the host provided no report source: ` +
+          `${reporting.map((rule) => rule.name).join(", ")}.`,
+      }),
+    );
+  }
+
+  // A `syntax` term needs a matcher for the language of every file in its
+  // scope. The probes are the files the campaign is proven on; a probe whose
+  // language has none would pass no probe and mean nothing.
+  const syntaxless = campaignRules.success.flatMap((rule) => {
+    if (!leafTermsOf(rule.detect).includes("syntax")) return [];
+    return [...rule.probes.fires, ...rule.probes.ignores].flatMap((probe) => {
+      const route = routeFor(routes.success, probe.path);
+      return route === undefined || route.language.syntax !== undefined
+        ? []
+        : [`${rule.name} (${probe.path}: ${route.language.id} carries no syntax matcher)`];
+    });
+  });
+  if (syntaxless.length > 0) {
+    return Result.fail(
+      new ConfigInvalid({
+        configPath,
+        detail:
+          `these campaigns hold a \`syntax\` term in a scope whose language has no syntax ` +
+          `matcher: ${[...new Set(syntaxless)].join(", ")}. Compose the language pack with ` +
+          `one (\`@goodbones/ast-grep\` for TypeScript), or write the detector without it.`,
+      }),
+    );
+  }
+
   // A probe carrying a source snippet is parsed by the extractor of the
   // language whose scope covers the probe's file — the same extractor the CLI
   // reads that file through. The plugin reads through oxlint's tree instead,
@@ -304,6 +466,19 @@ export const loadPolicy = (
     ),
     ...structureRulesFailingTheirProbe(structure.success),
     ...graphRulesFailingTheirProbe(graph.success),
+    ...campaignsFailingTheirProbe(
+      campaignRules.success,
+      extractor,
+      (file) => routeFor(routes.success, file)?.language.syntax ?? null,
+      functions,
+    ).map((failed) =>
+      failed.outOfScope === true
+        ? `${failed.name} (its probe ${failed.probe.path} is outside the campaign's own scope)`
+        : failed.expected === "fires"
+          ? `${failed.name} (fires probe ${failed.probe.path} did not fire)`
+          : `${failed.name} (ignores probe ${failed.probe.path} fired` +
+            (failed.admittedBy === undefined ? ")" : `, admitted by \`${failed.admittedBy}\`)`),
+    ),
   ];
   if (vacuous.length > 0) {
     return Result.fail(
@@ -325,6 +500,10 @@ export const loadPolicy = (
   const resolver = makeRouter(configPath, repoRoot, routes.success);
   if (Result.isFailure(resolver)) return Result.fail(resolver.failure);
 
+  const ledgerDir = config.ledger ?? DEFAULT_LEDGER_DIR;
+  const ledgers = readLedgers(configPath, fileSystem, ledgerDir, campaignRules.success);
+  if (Result.isFailure(ledgers)) return Result.fail(ledgers.failure);
+
   return Result.succeed({
     repoRoot,
     config,
@@ -335,11 +514,18 @@ export const loadPolicy = (
     graph: graph.success,
     adoption: rules.adoption,
     structure: structure.success,
+    campaignRules: campaignRules.success,
+    ledgers: ledgers.success,
+    ledgerDir,
+    functions,
+    reports: input.reports ?? NO_REPORTS,
+    now: input.now ?? Date.now(),
     fileSystem,
     languages,
     baseline: makeBaselineFilter(readBaseline(fileSystem, config.baseline)),
     resolver: resolver.success,
     extractor,
+    syntax: makeRoutingMatcher(routes.success),
     ignoreUnresolved: (config.resolve.ignoreUnresolved ?? []).map(
       (pattern: string) => new RegExp(pattern),
     ),

package/src/manifest/compile.ts

@@ -1,5 +1,7 @@
 import {
   type Allowance,
+  type CampaignRule,
+  type Detector,
   type ExportRule,
   type GraphConfig,
   type ImportRule,
@@ -15,11 +17,15 @@ import type { ManifestPath } from "../domain/manifest-location.js";
 import { fragmentOf, type Substitution } from "./expand.js";
 import { anchored, type CaptureIndex, globToRegexSource, prefixed } from "./glob.js";
 import {
+  type CampaignSpec,
+  type DetectorSpec,
+  durationMs,
   globsOf,
   type ImportsSpec,
   type Manifest,
   type ManifestNode,
   type NamingSpec,
+  type SyntaxTermSpec,
 } from "./manifest.js";
 
 // The manifest is the authoring surface; these flat rules are the machine's.
@@ -31,6 +37,8 @@ export type LoweredRules = {
   readonly members: ReadonlyArray<MemberRule>;
   readonly surface: ReadonlyArray<SurfaceRule>;
   readonly graph: GraphConfig;
+  // Campaigns pass through by their own id, as top-level `exports` rules do.
+  readonly campaigns: ReadonlyArray<CampaignRule>;
   // The nodes that said "not tightened yet", by name — the adoption backlog,
   // and what `limits` puts a ceiling on.
   readonly adoption: {
@@ -1050,13 +1058,226 @@ export const lowerManifest = (
     })),
   };
 
+  const campaigns = (manifest.campaigns ?? []).map((campaign) => lowerCampaign(campaign, aliases));
+
   return {
     imports,
     exports,
     members,
     surface,
     graph,
+    campaigns,
     adoption: { unrestricted: unrestrictedNodes, partial: partialNodes },
     structure: { roots, folders, parity, naming: namingRules },
   };
 };
+
+// The keys of a `syntax` term that belong to the engine's rule; `where` is
+// the one that does not.
+const SYNTAX_RULE_KEYS = [
+  "pattern",
+  "kind",
+  "regex",
+  "nthChild",
+  "inside",
+  "has",
+  "precedes",
+  "follows",
+  "all",
+  "any",
+  "not",
+] as const;
+
+const syntaxRuleOf = (term: SyntaxTermSpec): unknown =>
+  Object.fromEntries(
+    SYNTAX_RULE_KEYS.flatMap((key) => (term[key] === undefined ? [] : [[key, term[key]]])),
+  );
+
+// The leaf terms a path alone cannot exercise: each reads the file's text,
+// its syntax, or its facts, so a probe for a detector holding one must carry
+// a `source`.
+const TERMS_NEEDING_SOURCE = ["content", "syntax", "exports", "members", "fn"] as const;
+
+const leafTermsOf = (detector: DetectorSpec): ReadonlyArray<string> => {
+  if ("all" in detector) return detector.all.flatMap(leafTermsOf);
+  if ("any" in detector) return detector.any.flatMap(leafTermsOf);
+  if ("not" in detector) return leafTermsOf(detector.not);
+  return Object.keys(detector);
+};
+
+// A campaign's globs resolved: `scope` and a path-shaped `resolves` the way
+// graph rules resolve theirs, `exports`/`members` names the way `surface` and
+// `members` rules do, and the rest carried as written. The `fn` string is
+// kept verbatim for the loader, which holds the function it names.
+const lowerCampaign = (
+  campaign: CampaignSpec,
+  aliases: Readonly<Record<string, string>>,
+): CampaignRule => {
+  const asPath = (glob: string): string =>
+    prefixed(
+      globToRegexSource(expandAliases(glob, aliases), {}, { declaring: false, nextGroup: 1 })
+        .source,
+    );
+  const asName = (globs: string | ReadonlyArray<string>): ReadonlyArray<string> =>
+    globsOf(globs).map((one) =>
+      anchored(globToRegexSource(one, {}, { declaring: false, nextGroup: 1 }).source),
+    );
+  const name = `campaign/${campaign.id}`;
+
+  const lower = (detector: DetectorSpec): Detector => {
+    if ("all" in detector) return { all: detector.all.map(lower) };
+    if ("any" in detector) return { any: detector.any.map(lower) };
+    if ("not" in detector) return { not: lower(detector.not) };
+    if ("path" in detector) {
+      const { convention, ...rest } = detector.path;
+      const conventionSource =
+        convention === undefined
+          ? undefined
+          : typeof convention === "string"
+            ? CONVENTIONS[convention]?.source
+            : convention.regex;
+      if (convention !== undefined && conventionSource === undefined) {
+        throw new Error(`campaign "${campaign.id}" names an unknown convention "${convention}".`);
+      }
+      if (conventionSource !== undefined && rest.subject === undefined) {
+        throw new Error(
+          `campaign "${campaign.id}" states a path convention with no \`subject\`: say which ` +
+            `capture group of \`file\` holds the name the convention is about.`,
+        );
+      }
+      return {
+        path: {
+          file: globsOf(rest.file),
+          ...(rest.fileNot === undefined ? {} : { fileNot: globsOf(rest.fileNot) }),
+          ...(rest.subject === undefined ? {} : { subject: rest.subject }),
+          ...(conventionSource === undefined ? {} : { convention: conventionSource }),
+        },
+      };
+    }
+    if ("imports" in detector) {
+      const { resolves, symbols } = detector.imports;
+      return {
+        imports: {
+          resolves: typeof resolves === "string" ? asPath(resolves) : resolves,
+          ...(symbols === undefined ? {} : { symbols: [...symbols] }),
+        },
+      };
+    }
+    if ("exports" in detector) {
+      const term = detector.exports;
+      return {
+        exports: {
+          ...(term.name === undefined ? {} : { name: asName(term.name) }),
+          ...(term.kinds === undefined ? {} : { kinds: [...term.kinds] }),
+          ...(term.declares === undefined ? {} : { declares: [...term.declares] }),
+          ...(term.reexport === undefined ? {} : { reexport: term.reexport }),
+        },
+      };
+    }
+    if ("members" in detector) {
+      const term = detector.members;
+      return {
+        members: {
+          subject: term.subject,
+          ...(term.name === undefined ? {} : { name: asName(term.name) }),
+          ...(term.in === undefined ? {} : { in: asName(term.in) }),
+          ...(term.declares === undefined ? {} : { declares: [...term.declares] }),
+        },
+      };
+    }
+    if ("requires" in detector) return { requires: [...detector.requires] };
+    if ("content" in detector) return { content: { regex: detector.content.regex } };
+    if ("report" in detector) {
+      const term = detector.report;
+      if ((term.command === undefined) === (term.file === undefined)) {
+        throw new Error(
+          `campaign "${campaign.id}" has a report term that must name exactly one of ` +
+            `\`command\` (a program to run) and \`file\` (a report already written).`,
+        );
+      }
+      if (term.format === "regex" && term.pattern === undefined) {
+        throw new Error(
+          `campaign "${campaign.id}" has a \`regex\` report term with no \`pattern\`: give ` +
+            `one with named groups \`file\` and \`line\`.`,
+        );
+      }
+      return {
+        report: {
+          ...(term.command === undefined ? {} : { command: term.command }),
+          ...(term.file === undefined ? {} : { file: term.file }),
+          format: term.format,
+          ...(term.pattern === undefined ? {} : { pattern: term.pattern }),
+          ...(term.codes === undefined ? {} : { codes: [...term.codes] }),
+          ...(term.codesNot === undefined ? {} : { codesNot: [...term.codesNot] }),
+        },
+      };
+    }
+    if ("syntax" in detector) {
+      const { where } = detector.syntax;
+      const narrowed =
+        where === undefined
+          ? {}
+          : {
+              where: Object.fromEntries(
+                Object.entries(where).map(([capture, narrowing]) => [
+                  capture,
+                  {
+                    ...(narrowing.regex === undefined ? {} : { regex: narrowing.regex }),
+                    ...(narrowing.binding === undefined
+                      ? {}
+                      : {
+                          binding: {
+                            resolves:
+                              typeof narrowing.binding.resolves === "string"
+                                ? asPath(narrowing.binding.resolves)
+                                : narrowing.binding.resolves,
+                            ...(narrowing.binding.member === undefined
+                              ? {}
+                              : { member: [...narrowing.binding.member] }),
+                          },
+                        }),
+                  },
+                ]),
+              ),
+            };
+      return { syntax: { rule: syntaxRuleOf(detector.syntax), ...narrowed } };
+    }
+    return { fn: detector.fn };
+  };
+
+  // A probe without a source proves only the path; a detector that reads the
+  // file needs the file. Refused here, with the term named, rather than at
+  // load as a probe that mysteriously never fires.
+  const leaves = leafTermsOf(campaign.detect);
+  const needsSource = TERMS_NEEDING_SOURCE.filter((term) => leaves.includes(term));
+  const probes = [...campaign.probes.fires, ...(campaign.probes.ignores ?? [])];
+  const sourceless = probes.find((probe) => probe.source === undefined);
+  if (needsSource.length > 0 && sourceless !== undefined) {
+    throw new Error(
+      `campaign "${campaign.id}" has a probe (${sourceless.path}) with no \`source\`, and its ` +
+        `detector holds a ${needsSource.map((term) => `\`${term}\``).join(", ")} term, which ` +
+        `a path alone cannot exercise. Give every probe a source.`,
+    );
+  }
+  if (campaign.probes.fires.length === 0) {
+    throw new Error(
+      `campaign "${campaign.id}" carries no \`probes.fires\`. A campaign proves it can fire ` +
+        `the way every rule does; write at least one source it must report.`,
+    );
+  }
+
+  return {
+    name,
+    id: campaign.id,
+    ...(campaign.title === undefined ? {} : { title: campaign.title }),
+    message: campaign.how,
+    why: campaign.why,
+    ...(campaign.owner === undefined ? {} : { owner: campaign.owner }),
+    scope: globsOf(campaign.scope).map(asPath),
+    unit: campaign.unit,
+    detect: lower(campaign.detect),
+    probes: { fires: [...campaign.probes.fires], ignores: [...(campaign.probes.ignores ?? [])] },
+    staleAfter: durationMs(campaign.staleAfter),
+    onComplete: campaign.onComplete ?? "keep",
+  };
+};

package/src/manifest/json-schema.ts

@@ -31,9 +31,13 @@ const isObject = (value: JsonValue): value is JsonObject =>
 
 const isList = (value: JsonValue): value is ReadonlyArray<JsonValue> => Array.isArray(value);
 
-// The generator names the recursive node after its own internal wrapper. A
-// stable name is what a `$ref` in an error message or a docs page can point at.
-const DEFINITION_NAMES: Readonly<Record<string, string>> = { Suspend_: "ManifestNode" };
+// The generator names the recursive schemas after its own internal wrappers.
+// A stable name is what a `$ref` in an error message or a docs page can
+// point at: the tree's node, and a campaign's detector.
+const DEFINITION_NAMES: Readonly<Record<string, string>> = {
+  Suspend_: "ManifestNode",
+  Union_: "Detector",
+};
 
 const USE_REFERENCE = "#/$defs/Use";
 const INCLUDE_REFERENCE = "#/$defs/Include";