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

package/src/index.ts

@@ -14,6 +14,25 @@ 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,
+  reportSpecsOf,
+  type TermAnswer,
+} from "./core/campaigns.js";
 export {
   type Coverage,
   type CoverageFamily,
@@ -21,6 +40,12 @@ export {
   coverageOf,
   coverageShortfalls,
   fractionsOf,
+  type Reach,
+  reachOf,
+  type Residue,
+  residueOf,
+  type Vacancy,
+  vacancyOf,
 } from "./core/coverage.js";
 export {
   type BindingEdge,
@@ -37,17 +62,20 @@ export {
 export {
   type CompiledGraph,
   compileGraphRules,
+  cyclesIn,
   EMPTY_GRAPH_RULES,
   evaluateGraph,
   type Graph,
   graphRulesFailingTheirProbe,
   hasGraphRules,
+  heightOf,
 } from "./core/graph.js";
 export {
   type CompiledImportRule,
   compileImportRule,
   compileImportRules,
   evaluateImportEdge,
+  evaluateResolvedEdge,
   evaluateSelectedEdge,
   type ImportEdge,
   probeTargetOf,
@@ -55,6 +83,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,
@@ -62,6 +111,13 @@ export {
   memberRulesFailingTheirProbe,
   memberRulesSelecting,
 } from "./core/members.js";
+export {
+  type Concentration,
+  type ObservedEdge,
+  type Slack,
+  slackOf,
+  type SlackReport,
+} from "./core/slack.js";
 export {
   type CompiledStructure,
   compileStructure,
@@ -78,8 +134,13 @@ export {
   surfaceRulesSelecting,
 } from "./core/surface.js";
 export {
+  type Allowance,
   type BindingKind,
+  type CampaignProbe,
+  type CampaignRule,
+  type CampaignUnit,
   type DeclarationKind,
+  type Detector,
   type ExportFix,
   type ExportRule,
   type GraphConfig,
@@ -91,6 +152,7 @@ export {
   type ImportRule,
   type MemberRule,
   type MemberSubject,
+  type ProbeDiagnostic,
   type ResolveConfig,
   type ResolveScope,
   type StructureConfig,
@@ -100,6 +162,7 @@ export {
   ConfigInvalid,
   ImportUnresolved,
   PatternInvalid,
+  ReportUnavailable,
   ScopeInvalid,
 } from "./domain/architecture-error.js";
 export {
@@ -108,24 +171,118 @@ export {
   type MemberSite,
   type SourceFacts,
 } from "./domain/facts.js";
+export {
+  type ManifestLocator,
+  type ManifestPath,
+  type ManifestPosition,
+  renderManifestPath,
+} from "./domain/manifest-location.js";
+export {
+  type Diagnostic,
+  indexByFile,
+  parseReport,
+  type ParseReportOptions,
+  type ReportFormat,
+  uniqueDiagnostics,
+} from "./domain/report.js";
+export {
+  CONFORMANCE_MEASURES,
+  type ConformanceMeasure,
+  decodeSnapshot,
+  type Snapshot,
+  SNAPSHOT_SCHEMA_ID,
+  SNAPSHOT_VERSION,
+  type SnapshotCampaign,
+  type SnapshotConcentration,
+  snapshotJsonSchema,
+  Snapshot as SnapshotSchema,
+  type SnapshotSlack,
+  type SnapshotVacancy,
+  type SnapshotViolation,
+} from "./domain/snapshot.js";
 export {
   fingerprintOf,
   formatMessage,
   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 { DEFAULT_CONFIG_FILENAME, readManifestFile } from "./infrastructure/manifest-file.js";
-export { listSourceFiles, type WalkedLanguage } from "./infrastructure/walk.js";
+export {
+  findManifestFile,
+  formatManifestYaml,
+  MANIFEST_FILENAMES,
+  type ManifestFile,
+  readManifestFile,
+} from "./infrastructure/manifest-file.js";
+export {
+  expandIncludes,
+  type IncludedManifest,
+  type IncludeReader,
+  type SourceDocument,
+} from "./infrastructure/manifest-include.js";
+export { makeReportSourceLive } from "./infrastructure/report-source-live.js";
+export {
+  listPackageRoots,
+  listSourceFiles,
+  type PackagedLanguage,
+  type PackageRoot,
+  type WalkedLanguage,
+} from "./infrastructure/walk.js";
 export { type LoadedPolicy, loadPolicy, type LoadPolicyInput } from "./load/policy.js";
-export { type LoweredRules, lowerManifest, type ProbeLanguage } from "./manifest/compile.js";
 export {
+  type LoweredRules,
+  lowerManifest,
+  type LowerOptions,
+  type ProbeLanguage,
+} from "./manifest/compile.js";
+export {
+  type ExpandedManifest,
+  type ExpandIssue,
+  expandManifest,
+  type Origin,
+  originOf,
+  type Substitution,
+} from "./manifest/expand.js";
+export {
+  type Candidate,
+  candidatesOf,
+  type Generalization,
+  type InferInput,
+  inferManifest,
+  type InferOptions,
+  type InferPackage,
+  type Inferred,
+  type InferredTarget,
+  singularOf,
+} from "./manifest/infer.js";
+export {
+  MANIFEST_NODE_SCHEMA_ID,
+  MANIFEST_SCHEMA_ID,
+  manifestJsonSchema,
+  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";
@@ -134,3 +291,15 @@ export {
   type ModuleResolver,
   type ResolvedTarget,
 } from "./ports/module-resolver.js";
+export {
+  NO_REPORTS,
+  type ReportSource,
+  reportSourcesOf,
+  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/manifest-file.ts

@@ -1,17 +1,213 @@
+import { existsSync, readFileSync } from "node:fs";
+import * as path from "node:path";
 import { pathToFileURL } from "node:url";
 
+import {
+  type Document,
+  isAlias,
+  isMap,
+  isScalar,
+  isSeq,
+  LineCounter,
+  type Node,
+  type Pair,
+  parseDocument,
+  stringify,
+} from "yaml";
+
 import { ConfigInvalid } from "../domain/architecture-error.js";
+import type {
+  ManifestLocator,
+  ManifestPath,
+  ManifestPosition,
+} from "../domain/manifest-location.js";
+import { expandIncludes, type SourceDocument } from "./manifest-include.js";
+
+// The manifest, as the files on disk state it, before any decoding. A data
+// file — YAML, or JSON, which YAML 1.2 contains — is what any host in any
+// language can read, and is the form the docs are written in. A JavaScript
+// module is the escape hatch a Node host alone honours: for a manifest
+// generated from other data, and for what the ecosystem expects of a config
+// file. Either may `include` further data files, so a monorepo's policy can
+// live beside the packages it governs. Whichever it is, what comes out is one
+// `unknown` value for the decoder, and, from the data formats, a way to turn
+// a path in it back into a file and a line.
+
+// In discovery order. A repository with none of these is told all four; one
+// with more than one is refused, so nobody edits the wrong file for a week.
+export const MANIFEST_FILENAMES = [
+  "architecture.yaml",
+  "architecture.yml",
+  "architecture.json",
+  "architecture.config.mjs",
+] as const;
 
-export const DEFAULT_CONFIG_FILENAME = "architecture.config.mjs";
+export type ManifestFile = {
+  readonly configPath: string;
+  readonly manifest: unknown;
+  // Absent for a JavaScript module that includes nothing, which has no
+  // positions to give.
+  readonly locate: ManifestLocator | undefined;
+  // Every file the manifest was read from, the root first: what a host that
+  // caches or watches the policy has to look at.
+  readonly files: ReadonlyArray<string>;
+};
+
+export const findManifestFile = (repoRoot: string): string => {
+  const present = MANIFEST_FILENAMES.filter((name) => existsSync(path.resolve(repoRoot, name)));
+  const [found] = present;
+  if (found === undefined) {
+    throw new ConfigInvalid({
+      configPath: repoRoot,
+      detail:
+        `no architecture manifest found. Looked for ${MANIFEST_FILENAMES.join(", ")} ` +
+        `in this directory; \`architecture init\` writes a starter architecture.yaml.`,
+    });
+  }
+  if (present.length > 1) {
+    throw new ConfigInvalid({
+      configPath: repoRoot,
+      detail:
+        `more than one architecture manifest is present (${present.join(", ")}), and only one ` +
+        `can be the policy. Delete the others, or name one with ARCHITECTURE_CONFIG.`,
+    });
+  }
+  return path.resolve(repoRoot, found);
+};
+
+const extensionOf = (configPath: string): string => path.extname(configPath).toLowerCase();
+
+const isDataManifest = (configPath: string): boolean =>
+  [".yaml", ".yml", ".json"].includes(extensionOf(configPath));
+
+const isModuleManifest = (configPath: string): boolean =>
+  [".mjs", ".js", ".cjs"].includes(extensionOf(configPath));
+
+// Whichever form the root takes, an `include` in it names a data file, read
+// by the same parser; the locator that comes back answers across every file.
+export const readManifestFile = async (configPath: string): Promise<ManifestFile> => {
+  const root = isDataManifest(configPath)
+    ? parseDataFile(configPath)
+    : isModuleManifest(configPath)
+      ? await readModule(configPath)
+      : undefined;
+  if (root === undefined) {
+    throw new ConfigInvalid({
+      configPath,
+      detail:
+        "a manifest is a .yaml, .yml or .json file, or a .mjs/.js module — " +
+        `not ${JSON.stringify(path.basename(configPath))}.`,
+    });
+  }
+  const assembled = expandIncludes(configPath, root, { exists: existsSync, read: parseDataFile });
+  return {
+    configPath,
+    manifest: assembled.value,
+    locate: assembled.locate,
+    files: assembled.files,
+  };
+};
 
-// The manifest, as the file on disk states it, before any decoding. Today that
-// is a JavaScript module and its default export; a manifest in another format
-// changes this function and nothing behind it.
-export const readManifestFile = async (configPath: string): Promise<unknown> => {
+const readModule = async (configPath: string): Promise<SourceDocument> => {
   const module: unknown = await import(pathToFileURL(configPath).href).catch((cause: unknown) => {
     throw new ConfigInvalid({ configPath, detail: String(cause) });
   });
-  return typeof module === "object" && module !== null && "default" in module
-    ? module.default
-    : module;
+  const value =
+    typeof module === "object" && module !== null && "default" in module ? module.default : module;
+  return { value, locate: undefined };
 };
+
+// YAML 1.2 core schema, which is what a reader without a YAML background
+// expects: `on` and `no` are strings, not booleans. Merge keys (`<<`) resolve,
+// because the parser handles them before the manifest sees the document, and
+// duplicate keys are refused rather than last-one-wins. A tag the parser does
+// not know is refused too — a manifest is data, and a `!!js/function` in it
+// would be a manifest only one runtime could read.
+const parseDataFile = (configPath: string): SourceDocument => {
+  let text: string;
+  try {
+    text = readFileSync(configPath, "utf8");
+  } catch (cause) {
+    throw new ConfigInvalid({ configPath, detail: String(cause) });
+  }
+
+  const lines = new LineCounter();
+  const document = parseDocument(text, {
+    merge: true,
+    uniqueKeys: true,
+    customTags: [],
+    lineCounter: lines,
+    // A JSON file is read by the same parser; strict JSON is valid YAML.
+    schema: "core",
+  });
+  const problems = [...document.errors, ...document.warnings];
+  if (problems.length > 0) {
+    const file = path.basename(configPath);
+    throw new ConfigInvalid({
+      configPath,
+      detail:
+        "the manifest does not parse:\n" +
+        problems
+          .map((problem) => {
+            const [position] = problem.linePos ?? [];
+            const at =
+              position === undefined
+                ? ""
+                : `${file}:${String(position.line)}:${String(position.col)}  `;
+            return `  ${at}${problem.code}: ${problem.message.split("\n")[0] ?? problem.message}`;
+          })
+          .join("\n"),
+    });
+  }
+
+  return {
+    value: document.toJS({ mapAsMap: false }) as unknown,
+    locate: makeLocator(document, lines),
+  };
+};
+
+const keyMatches = (pair: Pair, segment: PropertyKey): boolean =>
+  isScalar(pair.key) && String(pair.key.value) === String(segment);
+
+// Walks the document's own tree by the decoder's path and answers with the
+// position of the deepest thing that exists along it. A map key is reported
+// at the key, where the reader's eye lands; a sequence item at the item. A
+// key merged in through `<<` lives in the fragment it came from, which the
+// walk cannot see — the reader then gets the position of the map instead.
+const makeLocator = (document: Document, lines: LineCounter): ManifestLocator => {
+  const positionOf = (node: Node | null | undefined): ManifestPosition | null => {
+    const offset = node?.range?.[0];
+    if (offset === undefined) return null;
+    const { col, line } = lines.linePos(offset);
+    return { line, column: col };
+  };
+  const resolved = (node: unknown): unknown => (isAlias(node) ? node.resolve(document) : node);
+
+  return (manifestPath: ManifestPath) => {
+    let current: unknown = resolved(document.contents);
+    let position = positionOf(document.contents);
+    for (const segment of manifestPath) {
+      if (isMap(current)) {
+        const pair = current.items.find((one) => keyMatches(one, segment));
+        if (pair === undefined) break;
+        position = positionOf(isScalar(pair.key) ? pair.key : null) ?? position;
+        current = resolved(pair.value);
+      } else if (isSeq(current) && typeof segment === "number") {
+        const item = current.items[segment];
+        if (item === undefined) break;
+        position = positionOf(item as Node) ?? position;
+        current = resolved(item);
+      } else {
+        break;
+      }
+    }
+    return position;
+  };
+};
+
+// The value as a YAML document, for `architecture migrate` and anything else
+// that writes a manifest rather than reads one. Strings are quoted whenever
+// the core schema would read them as something else, and a multi-line one —
+// a probe source — becomes a block scalar.
+export const formatManifestYaml = (manifest: unknown): string =>
+  stringify(manifest, { lineWidth: 100, blockQuote: "literal", schema: "core" });