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

package/src/manifest/json-schema.ts

@@ -0,0 +1,168 @@
+import * as Schema from "effect/Schema";
+
+import { Manifest } from "./manifest.js";
+
+// The manifest's shape as a JSON Schema, generated from the same codec that
+// decodes it, so the two cannot disagree. A YAML file names it in a header
+// comment and a JSON file in a `$schema` key; either way the editor completes
+// keys and flags a misspelled one before the loader ever runs.
+//
+// Three things the codec does not know are added here: the `defs` map, the
+// `{ use }` reference form that may stand in for any object, and the
+// `{ include }` form that may stand in for any object or list — all belong to
+// the passes that run before decoding.
+
+export const MANIFEST_SCHEMA_ID =
+  "https://dataquail.github.io/goodbones/schema/architecture.schema.json";
+
+// The schema an included file names: one node of the tree, with the two keys
+// a file of its own may carry at the top.
+export const MANIFEST_NODE_SCHEMA_ID =
+  "https://dataquail.github.io/goodbones/schema/architecture-node.schema.json";
+
+type JsonValue = string | number | boolean | null | JsonObject | ReadonlyArray<JsonValue>;
+type JsonObject = { readonly [key: string]: JsonValue };
+
+const entriesOf = (value: JsonObject): ReadonlyArray<readonly [string, JsonValue]> =>
+  Object.entries(value);
+
+const isObject = (value: JsonValue): value is JsonObject =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const isList = (value: JsonValue): value is ReadonlyArray<JsonValue> => Array.isArray(value);
+
+// 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";
+
+const Use: JsonObject = {
+  type: "object",
+  description:
+    "A reference to a fragment under the top-level `defs`. Replaced by a copy of the fragment before the manifest is decoded; any other key written beside `use` overrides the fragment's key of the same name.",
+  properties: { use: { type: "string" } },
+  required: ["use"],
+};
+
+const Include: JsonObject = {
+  type: "object",
+  description:
+    "A reference to another YAML or JSON file, relative to this one. Replaced by that file's whole value before the manifest is decoded; a list item naming a file that holds a list is spliced in. Nothing may be written beside `include`.",
+  properties: { include: { type: "string" } },
+  required: ["include"],
+  additionalProperties: false,
+};
+
+// Every object schema below the root becomes "this object, or a `use` of a
+// fragment shaped like it, or an `include` of a file holding one", and every
+// list schema "this list, or an `include` of a file holding one". The
+// expansion passes replace a reference wherever it stands, so the schema
+// admits one wherever the value may stand.
+const admitReferences = (value: JsonValue): JsonValue => {
+  if (Array.isArray(value)) return value.map(admitReferences);
+  if (!isObject(value)) return value;
+
+  const rebuilt: Record<string, JsonValue> = {};
+  for (const [key, entry] of entriesOf(value)) {
+    if (key === "$ref" && typeof entry === "string") {
+      const name = entry.replace(/^#\/\$defs\//, "");
+      rebuilt[key] = `#/$defs/${DEFINITION_NAMES[name] ?? name}`;
+    } else {
+      rebuilt[key] = admitReferences(entry);
+    }
+  }
+  if (rebuilt.type === "object" && "properties" in rebuilt) {
+    return { anyOf: [{ $ref: USE_REFERENCE }, { $ref: INCLUDE_REFERENCE }, rebuilt] };
+  }
+  if (rebuilt.type === "array") {
+    return { anyOf: [{ $ref: INCLUDE_REFERENCE }, rebuilt] };
+  }
+  return rebuilt;
+};
+
+const DEFS_PROPERTY: JsonObject = {
+  type: "object",
+  description:
+    'Named fragments, referenced elsewhere in the manifest as `{ use: "<name>" }`. A fragment may itself contain `use`. Every file\'s `defs` share one namespace.',
+  additionalProperties: true,
+};
+
+const SCHEMA_PROPERTY: JsonObject = {
+  type: "string",
+  description: "For editors. Ignored by the loader.",
+};
+
+export const manifestJsonSchema = (): JsonObject => {
+  const generated = Schema.toJsonSchemaDocument(Manifest) as unknown as {
+    readonly schema: JsonObject;
+    readonly definitions: JsonObject;
+  };
+  const { properties, ...root } = generated.schema;
+  if (properties === undefined || !isObject(properties)) {
+    throw new Error("the manifest schema generated with no properties");
+  }
+
+  const definitions: Record<string, JsonValue> = {};
+  for (const [name, definition] of entriesOf(generated.definitions)) {
+    definitions[DEFINITION_NAMES[name] ?? name] = admitReferences(definition);
+  }
+
+  return {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: MANIFEST_SCHEMA_ID,
+    title: "Architecture manifest",
+    description:
+      "One manifest of a repository's architecture, read by @goodbones/cli and @goodbones/oxlint. See https://dataquail.github.io/goodbones/architecture-rules/manifest/.",
+    ...root,
+    properties: {
+      $schema: SCHEMA_PROPERTY,
+      defs: DEFS_PROPERTY,
+      ...Object.fromEntries(
+        entriesOf(properties).map(([key, value]) => [key, admitReferences(value)]),
+      ),
+    },
+    $defs: { ...definitions, Use, Include },
+  };
+};
+
+// One node of the tree as a file of its own — what a per-package
+// `architecture.yaml` that the root manifest `include`s is shaped like. The
+// node's object form, with the `$schema` and `defs` keys such a file may carry
+// at the top, over the same definitions as the whole manifest.
+export const manifestNodeJsonSchema = (): JsonObject => {
+  const whole = manifestJsonSchema();
+  const definitions = whole.$defs;
+  if (definitions === undefined || !isObject(definitions)) {
+    throw new Error("the manifest schema generated with no definitions");
+  }
+  const node = definitions.ManifestNode;
+  const variants = node !== undefined && isObject(node) ? node.anyOf : undefined;
+  const object =
+    variants !== undefined && isList(variants)
+      ? variants.find((variant) => isObject(variant) && variant.type === "object")
+      : undefined;
+  if (object === undefined || !isObject(object)) {
+    throw new Error("the manifest schema generated with no object form of a node");
+  }
+  const { $id: _id, $schema: _schema, ...rest } = object;
+  return {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: MANIFEST_NODE_SCHEMA_ID,
+    title: "Architecture manifest node",
+    description:
+      "One node of an architecture manifest's tree, as a file the manifest includes. See https://dataquail.github.io/goodbones/architecture-rules/manifest/#splitting-the-manifest-include.",
+    ...rest,
+    properties: {
+      $schema: SCHEMA_PROPERTY,
+      defs: DEFS_PROPERTY,
+      ...(rest.properties !== undefined && isObject(rest.properties) ? rest.properties : {}),
+    },
+    $defs: definitions,
+  };
+};

package/src/manifest/manifest.ts

@@ -1,8 +1,22 @@
 import * as Result from "effect/Result";
 import * as Schema from "effect/Schema";
-
-import { DeclarationKind, ResolveConfig } from "../domain/architecture-config.js";
+import * as SchemaIssue from "effect/SchemaIssue";
+
+import {
+  CampaignUnit,
+  DeclarationKind,
+  ImportProbeTarget,
+  ProbeDiagnostic,
+  ReportFormat,
+  ResolveConfig,
+} from "../domain/architecture-config.js";
 import { ConfigInvalid } from "../domain/architecture-error.js";
+import {
+  type ManifestLocator,
+  type ManifestPath,
+  renderManifestPath,
+} from "../domain/manifest-location.js";
+import { expandManifest, originOf, type Substitution } from "./expand.js";
 
 // A manifest is a tree of nodes keyed by path pattern, where everything the
 // architecture says about a part of the tree is written at that part of the tree.
@@ -247,10 +261,220 @@ const CoverageFloors = Schema.Struct({
   graph: Schema.optionalKey(Schema.Finite),
 });
 
+// Ceilings on the conformance measures — what `architecture conformance`
+// counts and `check` does not otherwise gate: the files no family reaches,
+// the nodes no file is under, the allowances nothing imports through, and
+// the fragment entries used at fewer than half the nodes granted them. Each
+// is a count that only goes down: lowered when the number falls, never
+// raised to make a red run green.
+const ConformanceCeilings = Schema.Struct({
+  residue: Schema.optionalKey(Schema.Finite),
+  vacant: Schema.optionalKey(Schema.Finite),
+  slack: Schema.optionalKey(Schema.Finite),
+  concentration: Schema.optionalKey(Schema.Finite),
+});
+
 const Limits = Schema.Struct({
   unrestricted: Schema.optionalKey(Schema.Finite),
   partial: Schema.optionalKey(Schema.Finite),
   coverage: Schema.optionalKey(CoverageFloors),
+  conformance: Schema.optionalKey(ConformanceCeilings),
+});
+
+// A campaign: a migration the repository is running, tracked as an object —
+// a detector, a rationale, a guide, an owner, a definition of done, and a
+// ledger of every place the pattern still occurs. Where a rule says what may
+// never happen, a campaign names what the code is moving away from.
+//
+// The detector is a predicate algebra: `all`, `any` and `not` over leaf
+// terms, the same three words ast-grep uses. Leaf terms reuse the other
+// families' vocabularies where one exists.
+
+// A regular expression over the whole repo-relative path, matched as the
+// `structure` naming rules are: with `subject` and `convention`, the capture
+// group named holds the name being judged, and the term holds when the name
+// has the convention's shape.
+const PathTerm = Schema.Struct({
+  file: Globs,
+  fileNot: Schema.optionalKey(Globs),
+  subject: Schema.optionalKey(Schema.Finite),
+  convention: Schema.optionalKey(SurfaceConvention),
+});
+
+// Holds when some import of the file resolves to the target — a path glob,
+// `{ external: <package> }` or `{ builtin: <module> }` — and, with `symbols`,
+// pulls one of those names across it.
+const ImportsTerm = Schema.Struct({
+  resolves: ImportProbeTarget,
+  symbols: Schema.optionalKey(Schema.Array(Schema.String)),
+});
+
+// Holds for an export site the selectors admit — the `surface` selectors.
+const ExportsTerm = Schema.Struct({
+  name: Schema.optionalKey(Globs),
+  kinds: Schema.optionalKey(Schema.Array(Schema.Literals(["named", "default", "namespace"]))),
+  declares: Schema.optionalKey(Schema.Array(DeclarationKind)),
+  reexport: Schema.optionalKey(Schema.Boolean),
+});
+
+// Holds for a member site the selectors admit — the `members` selectors.
+const MembersTerm = Schema.Struct({
+  subject: Schema.Literals(["members", "calls"]),
+  name: Schema.optionalKey(Globs),
+  in: Schema.optionalKey(Globs),
+  declares: Schema.optionalKey(Schema.Array(DeclarationKind)),
+});
+
+// A regular expression over the file's text, multiline.
+const ContentTerm = Schema.Struct({ regex: Schema.String });
+
+// How a metavariable is narrowed: by the text it captured, or by what the
+// identifier at its root is bound to — the module it resolves to and the
+// name it was imported as (`member`), which is how `class $N extends $BASE`
+// says "a React component" rather than "any class with a base".
+const CaptureNarrowing = Schema.Struct({
+  regex: Schema.optionalKey(Schema.String),
+  binding: Schema.optionalKey(
+    Schema.Struct({
+      resolves: ImportProbeTarget,
+      member: Schema.optionalKey(Schema.Array(Schema.String)),
+    }),
+  ),
+});
+
+// An ast-grep rule object — `pattern`, `kind`, `regex`, `has`, `inside`,
+// `precedes`, `follows`, `nthChild`, `all`, `any`, `not` — with `where`
+// beside it. The rule is the engine's to validate; the manifest only knows
+// which keys are a rule's and which is the narrowing. `kind` names are the
+// engine's node kinds, which today are tree-sitter's.
+const SyntaxTerm = Schema.Struct({
+  pattern: Schema.optionalKey(Schema.Unknown),
+  kind: Schema.optionalKey(Schema.Unknown),
+  regex: Schema.optionalKey(Schema.Unknown),
+  nthChild: Schema.optionalKey(Schema.Unknown),
+  inside: Schema.optionalKey(Schema.Unknown),
+  has: Schema.optionalKey(Schema.Unknown),
+  precedes: Schema.optionalKey(Schema.Unknown),
+  follows: Schema.optionalKey(Schema.Unknown),
+  all: Schema.optionalKey(Schema.Unknown),
+  any: Schema.optionalKey(Schema.Unknown),
+  not: Schema.optionalKey(Schema.Unknown),
+  where: Schema.optionalKey(Schema.Record(Schema.String, CaptureNarrowing)),
+});
+
+// One program to run or file to read, or several: a tool that takes one
+// project at a time is run once per project, and the outputs are read as
+// one report — a diagnostic two of them print is one diagnostic.
+const ReportSources = Schema.Union([
+  Schema.String,
+  Schema.Array(Schema.String).check(Schema.isMinLength(1)),
+]);
+
+// A finding of another program, read from the output of `command` (run
+// from the repository root, once per `check`) or from `file` (written by
+// an earlier step) in one of the known formats — `tsc`, `eslint --format
+// json`, `oxlint --format json` — or by a `regex` with named groups. Holds
+// for each diagnostic on the file whose code the term speaks to.
+const ReportTerm = Schema.Struct({
+  command: Schema.optionalKey(ReportSources),
+  file: Schema.optionalKey(ReportSources),
+  format: ReportFormat,
+  pattern: Schema.optionalKey(Schema.String),
+  codes: Schema.optionalKey(Schema.Array(Schema.String)),
+  codesNot: Schema.optionalKey(Schema.Array(Schema.String)),
+}).check(
+  // Refused at decode, where the issue names a line, rather than in the
+  // lowering: a term that names both sources or neither, and a `regex`
+  // term with nothing to match lines against.
+  Schema.makeFilter((term) => {
+    const issues: Array<Schema.FilterIssue> = [];
+    if ((term.command === undefined) === (term.file === undefined)) {
+      issues.push(
+        "a report term names exactly one of `command` (a program to run) and `file` (a report already written)",
+      );
+    }
+    if (term.format === "regex" && term.pattern === undefined) {
+      issues.push({
+        path: ["pattern"],
+        issue: "a `regex` report term needs a `pattern` with named groups `file` and `line`",
+      });
+    }
+    return issues;
+  }),
+);
+
+export type DetectorSpec =
+  | { readonly all: ReadonlyArray<DetectorSpec> }
+  | { readonly any: ReadonlyArray<DetectorSpec> }
+  | { readonly not: DetectorSpec }
+  | { readonly path: typeof PathTerm.Type }
+  | { readonly imports: typeof ImportsTerm.Type }
+  | { readonly exports: typeof ExportsTerm.Type }
+  | { readonly members: typeof MembersTerm.Type }
+  // The `structure` parity strings: holds when every named sibling exists.
+  | { readonly requires: ReadonlyArray<string> }
+  | { readonly content: typeof ContentTerm.Type }
+  | { readonly syntax: typeof SyntaxTerm.Type }
+  | { readonly report: typeof ReportTerm.Type }
+  // `module#export`: a predicate function the host imports before loading.
+  | { readonly fn: string };
+
+// Each object carries exactly one term key, so a misspelled one is a decode
+// error that names the line rather than a term quietly dropped.
+const DetectorRef = Schema.suspend((): Schema.Codec<DetectorSpec> => DetectorSpec);
+
+const DetectorSpec = Schema.Union([
+  Schema.Struct({ all: Schema.Array(DetectorRef) }),
+  Schema.Struct({ any: Schema.Array(DetectorRef) }),
+  Schema.Struct({ not: DetectorRef }),
+  Schema.Struct({ path: PathTerm }),
+  Schema.Struct({ imports: ImportsTerm }),
+  Schema.Struct({ exports: ExportsTerm }),
+  Schema.Struct({ members: MembersTerm }),
+  Schema.Struct({ requires: Schema.Array(Schema.String) }),
+  Schema.Struct({ content: ContentTerm }),
+  Schema.Struct({ syntax: SyntaxTerm }),
+  Schema.Struct({ report: ReportTerm }),
+  Schema.Struct({ fn: Schema.String }),
+]);
+
+// A source the campaign is proven against at load. `path` alone proves a
+// path-shaped detector; `source` is parsed, `edges` answers the `imports`
+// term and a binding narrowing in place of the live resolver, `files`
+// answers `requires` in place of the file system, and `report` answers a
+// `report` term in place of running anything — one-based positions, as a
+// tool prints them.
+const CampaignProbe = Schema.Struct({
+  path: Schema.String,
+  source: Schema.optionalKey(Schema.String),
+  edges: Schema.optionalKey(Schema.Record(Schema.String, ImportProbeTarget)),
+  files: Schema.optionalKey(Schema.Array(Schema.String)),
+  report: Schema.optionalKey(Schema.Array(ProbeDiagnostic)),
+});
+
+// `30d`, `12h`: how long a campaign may go without progress before the
+// conformance report calls it stalled.
+const Duration = Schema.String.check(Schema.isPattern(/^\d+[dh]$/));
+
+const Campaign = Schema.Struct({
+  // The ledger file's name, and the rule name's tail: `campaign/<id>`.
+  id: Schema.String.check(Schema.isPattern(/^[a-z0-9]+(?:-[a-z0-9]+)*$/)),
+  title: Schema.optionalKey(Schema.String),
+  why: Schema.String,
+  // What a reader at a hit does about it — the message every hit carries.
+  how: Schema.String,
+  owner: Schema.optionalKey(Schema.String),
+  // Which files the campaign selects. Alias-aware globs, as the graph rules
+  // take; a campaign's reach is its scope, so it joins no coverage row.
+  scope: Globs,
+  unit: CampaignUnit,
+  detect: DetectorSpec,
+  probes: Schema.Struct({
+    fires: Schema.Array(CampaignProbe),
+    ignores: Schema.optionalKey(Schema.Array(CampaignProbe)),
+  }),
+  staleAfter: Duration,
+  onComplete: Schema.optionalKey(Schema.Literals(["keep", "remove"])),
 });
 
 export const Manifest = Schema.Struct({
@@ -267,6 +491,10 @@ export const Manifest = Schema.Struct({
   exports: Schema.optionalKey(Schema.Array(ExportRestriction)),
   graph: Schema.optionalKey(Graph),
   limits: Schema.optionalKey(Limits),
+  campaigns: Schema.optionalKey(Schema.Array(Campaign)),
+  // Where each campaign's ledger is written: `<ledger>/<id>.json`, relative
+  // to the manifest. Defaults to `.architecture-campaigns`.
+  ledger: Schema.optionalKey(Schema.String),
   // Shorthands expanded in every glob, so a pattern reads the way the repo's own
   // imports do rather than repeating `packages/server/src` on every line.
   aliases: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)),
@@ -282,17 +510,36 @@ export type GraphSpec = typeof Graph.Type;
 export type LimitsSpec = typeof Limits.Type;
 export type NamingSpec = typeof Naming.Type;
 export type ExportRestriction = typeof ExportRestriction.Type;
+export type CampaignSpec = typeof Campaign.Type;
+export type CampaignProbeSpec = typeof CampaignProbe.Type;
+export type SyntaxTermSpec = typeof SyntaxTerm.Type;
+
+export const DEFAULT_LEDGER_DIR = ".architecture-campaigns";
+
+// `30d` → milliseconds. The schema has already refused any other shape.
+export const durationMs = (duration: string): number => {
+  const amount = Number(duration.slice(0, -1));
+  return amount * (duration.endsWith("h") ? 3_600_000 : 86_400_000);
+};
 
 export const globsOf = (globs: string | ReadonlyArray<string>): ReadonlyArray<string> =>
   typeof globs === "string" ? [globs] : globs;
 
-const decode = Schema.decodeUnknownResult(Manifest);
+// Every issue, not the first: a manifest is edited by hand, and the reader
+// fixing one line wants to know about the other three. A key the schema does
+// not declare is refused rather than dropped — a misspelled `matchNot` that
+// decoded to nothing would be a rule quietly enforcing less than it says.
+const decode = Schema.decodeUnknownResult(Manifest, { errors: "all", onExcessProperty: "error" });
+const flatten = SchemaIssue.makeFormatterStandardSchemaV1();
 
 export type DecodedManifest = {
   readonly manifest: Manifest;
   // Things the manifest said in a form that still loads but is on its way out.
   // The host prints them; nothing else acts on them.
   readonly notices: ReadonlyArray<string>;
+  // Every `use` the expansion replaced. Lowering reads them to say which
+  // fragment an allowance came through; nothing else needs them.
+  readonly substitutions: ReadonlyArray<Substitution>;
 };
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
@@ -392,17 +639,98 @@ const normalizeLegacyMembers = (
   return { input: { ...input, tree }, notices };
 };
 
+export type DecodeManifestOptions = {
+  // Turns a path in the file into a line and column. The YAML reader supplies
+  // one; a JavaScript module has no positions to give and passes nothing.
+  readonly locate?: ManifestLocator | undefined;
+};
+
+const fileLabelOf = (configPath: string): string => configPath.split(/[\\/]/).at(-1) ?? configPath;
+
+// A position carries its own file when the value was written in a file the
+// manifest `include`d; otherwise it is in the manifest file itself.
+const positionOf = (
+  file: string,
+  locate: ManifestLocator | undefined,
+  path: ManifestPath,
+): string | null => {
+  const found = locate?.(path) ?? null;
+  return found === null
+    ? null
+    : `${found.file ?? file}:${String(found.line)}:${String(found.column)}`;
+};
+
+// One line per issue: where in the file, which path, what was wrong — and,
+// when the value came in through a `use`, the reference that pulled it in,
+// since the fragment's own line may sit far from where the reader is looking.
+const describeIssue = (
+  configPath: string,
+  locate: ManifestLocator | undefined,
+  substitutions: ReadonlyArray<Substitution>,
+  path: ManifestPath,
+  detail: string,
+): string => {
+  const file = fileLabelOf(configPath);
+  const origin = originOf(substitutions, path);
+  const at = positionOf(file, locate, origin.path);
+  const via = origin.via.map(({ at: ref, name }) => {
+    const position = positionOf(file, locate, ref);
+    return `via \`use: ${JSON.stringify(name)}\`${position === null ? "" : ` at ${position}`}`;
+  });
+  return (
+    `  ${at === null ? "" : `${at}  `}${renderManifestPath(origin.path)}: ${detail}` +
+    (via.length === 0 ? "" : ` (${via.join(", ")})`)
+  );
+};
+
+// The standard-schema formatter flattens the issue tree to `{ path, message }`
+// pairs; a path segment may arrive wrapped as `{ key }`.
+const pathOf = (issue: {
+  readonly path?: ReadonlyArray<PropertyKey | { readonly key: PropertyKey }> | undefined;
+}): ManifestPath =>
+  (issue.path ?? []).map((segment) => (typeof segment === "object" ? segment.key : segment));
+
 export const decodeManifest = (
   configPath: string,
   input: unknown,
+  options: DecodeManifestOptions = {},
 ): Result.Result<DecodedManifest, ConfigInvalid> => {
-  const resolve = normalizeLegacyResolve(input);
+  const expanded = expandManifest(input);
+  if (Result.isFailure(expanded)) {
+    return Result.fail(
+      new ConfigInvalid({
+        configPath,
+        detail:
+          "the manifest does not expand:\n" +
+          describeIssue(
+            configPath,
+            options.locate,
+            [],
+            expanded.failure.path,
+            expanded.failure.detail,
+          ),
+      }),
+    );
+  }
+  const { substitutions, value } = expanded.success;
+
+  const resolve = normalizeLegacyResolve(value);
   const members = normalizeLegacyMembers(resolve.input);
-  return Result.map(
-    Result.mapError(
-      decode(members.input),
-      (issue) => new ConfigInvalid({ configPath, detail: String(issue) }),
-    ),
-    (manifest) => ({ manifest, notices: [...resolve.notices, ...members.notices] }),
-  );
+  const decoded = decode(members.input);
+  if (Result.isFailure(decoded)) {
+    const lines = flatten(decoded.failure.issue).issues.map((issue) =>
+      describeIssue(configPath, options.locate, substitutions, pathOf(issue), issue.message),
+    );
+    return Result.fail(
+      new ConfigInvalid({
+        configPath,
+        detail: `the manifest does not decode:\n${lines.join("\n")}`,
+      }),
+    );
+  }
+  return Result.succeed({
+    manifest: decoded.success,
+    notices: [...resolve.notices, ...members.notices],
+    substitutions,
+  });
 };

package/src/ports/campaign-predicate.ts

@@ -0,0 +1,30 @@
+import type { SourceFacts } from "../domain/facts.js";
+import type { SyntaxTree } from "./syntax-matcher.js";
+
+// The floor of a campaign's detector: a predicate function the repository
+// writes, named from the manifest as `module#export` and handed to the
+// policy by the host. It is given what the evaluator has about one file and
+// answers either a verdict about the file or the subjects it found in it —
+// a declaration name, or any key a `match` campaign should ledger — each
+// optionally with where it sits. Exported as a public type so a referenced
+// module typechecks on its own.
+
+export type Range = {
+  // Zero-based.
+  readonly start: { readonly line: number; readonly column: number };
+  readonly end: { readonly line: number; readonly column: number };
+};
+
+export type CampaignPredicateInput = {
+  readonly file: string;
+  readonly text: string;
+  readonly facts: SourceFacts;
+  // The file parsed by the scope's syntax matcher, or `null` without one.
+  readonly syntax: SyntaxTree | null;
+};
+
+export type CampaignSubject = { readonly subject: string; readonly range?: Range };
+
+export type CampaignPredicate = (
+  input: CampaignPredicateInput,
+) => boolean | ReadonlyArray<CampaignSubject>;

package/src/ports/language.ts

@@ -4,6 +4,7 @@ import type { ExportFix, ResolveScope } from "../domain/architecture-config.js";
 import type { ScopeInvalid } from "../domain/architecture-error.js";
 import type { FactExtractor } from "./fact-extractor.js";
 import type { ModuleResolver } from "./module-resolver.js";
+import type { SyntaxMatcher } from "./syntax-matcher.js";
 
 // Everything the policy needs from one programming language, behind one port.
 //
@@ -21,6 +22,17 @@ export type Language = {
   // Files carrying one of those extensions that are not source — for
   // TypeScript, a declaration file states types and no linter visits one.
   readonly ignoredFiles: ReadonlyArray<RegExp>;
+  // The files whose presence makes a folder a package of this language —
+  // `package.json`, `go.mod`, `Cargo.toml`. `infer` counts its depth from a
+  // package rather than from the repository root, so a monorepo of twenty
+  // packages is described one package at a time. Empty if the ecosystem has no
+  // such marker.
+  readonly packageMarkers: ReadonlyArray<string>;
+  // The folder names a package of this language keeps its source under, in
+  // order of preference — `src` for TypeScript, nothing for Go, where source
+  // sits at the package root. The first one that exists is where `infer`
+  // starts counting.
+  readonly sourceRoots: ReadonlyArray<string>;
   // Reads the facts out of one source text. The CLI reads every file through
   // it, and a probe carrying a `source` snippet is parsed by it at load.
   readonly extractor: FactExtractor;
@@ -28,6 +40,11 @@ export type Language = {
   // carry out. A rewrite is written in one module syntax; a rule naming one no
   // loaded language implements is refused at load.
   readonly fixes: ReadonlyArray<ExportFix>;
+  // Finds expressions of a given shape in one file, for a campaign's `syntax`
+  // term. Optional: a pack without one still answers every other family, and
+  // a campaign that needs one in its scope is refused at load with a
+  // sentence naming the language.
+  readonly syntax?: SyntaxMatcher;
   // A resolver for the files one scope covers. Built once per scope per run;
   // resolution is the expensive half of linting an architecture. The scope's
   // `options` are this language's to read, and anything it does not

package/src/ports/report-source.ts

@@ -0,0 +1,35 @@
+import type { Diagnostic, ReportFormat } from "../domain/report.js";
+
+// What a `report` term names: a program to run from the repository root, or
+// a file some earlier step wrote — or several of either, read as one report
+// — and the format the output is read in.
+export type ReportSpec = {
+  readonly command?: string | ReadonlyArray<string> | undefined;
+  readonly file?: string | ReadonlyArray<string> | undefined;
+  readonly format: ReportFormat;
+  // `regex` only.
+  readonly pattern?: string | undefined;
+};
+
+// The commands or files a spec names, as a list.
+export const reportSourcesOf = (spec: ReportSpec): ReadonlyArray<string> => {
+  const named = spec.command ?? spec.file ?? [];
+  return typeof named === "string" ? [named] : named;
+};
+
+// Answers a `report` term for one file. The live source runs the commands
+// once per process (a report is about the whole repository, and a campaign
+// asks per file) and reads a file once; a fake answers from a table. The
+// core never spawns anything.
+//
+// `read` is the host's chance to ask ahead: it reads the report — several
+// commands at once — and keeps the answer, or the failure, for
+// `diagnosticsOf` to hand back. Both hosts call it before any file is
+// judged; a source that does not offer it is asked synchronously, one
+// command after another, the first time a file asks.
+export type ReportSource = {
+  readonly diagnosticsOf: (spec: ReportSpec, file: string) => ReadonlyArray<Diagnostic>;
+  readonly read?: ((spec: ReportSpec) => Promise<void>) | undefined;
+};
+
+export const NO_REPORTS: ReportSource = { diagnosticsOf: () => [] };