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

package/src/index.ts

@@ -3,6 +3,15 @@
 // manifest into a policy. A host composes these with a language pack and the
 // live file system; a language pack implements the ports. Nothing here names a
 // language. The fakes are under `@goodbones/core/testing`.
+//
+// A family the core does not own — `campaigns`, in @goodbones/campaigns —
+// arrives as a `PolicyExtension` the host passes to `loadPolicy`: it claims
+// its own manifest keys, decodes them with its own codec, and reads its state
+// back off `LoadedPolicy.extensions`. What such a family needs from here is
+// exported deliberately: the glob primitives its lowering must match
+// character for character, the pattern vocabulary its detectors share with
+// the other families, and `lowerManifest` itself, which an `endState` runs a
+// sector-relative tree through.
 export {
   type Baseline,
   type BaselineFilter,
@@ -21,6 +30,12 @@ export {
   coverageOf,
   coverageShortfalls,
   fractionsOf,
+  type Reach,
+  reachOf,
+  type Residue,
+  residueOf,
+  type Vacancy,
+  vacancyOf,
 } from "./core/coverage.js";
 export {
   type BindingEdge,
@@ -37,17 +52,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,
@@ -62,12 +80,30 @@ export {
   memberRulesFailingTheirProbe,
   memberRulesSelecting,
 } from "./core/members.js";
+export {
+  compilePatterns,
+  firstFromMatch,
+  matchesAny,
+  type Selectable,
+  sourcesOf,
+  targetAllowed,
+  type Targeted,
+  validateTargetPatterns,
+} from "./core/patterns.js";
+export {
+  type Concentration,
+  type ObservedEdge,
+  type Slack,
+  slackOf,
+  type SlackReport,
+} from "./core/slack.js";
 export {
   type CompiledStructure,
   compileStructure,
   EMPTY_STRUCTURE,
   evaluateStructure,
   requiredSiblingsOf,
+  siblingsOf,
   structureRulesFailingTheirProbe,
 } from "./core/structure.js";
 export {
@@ -78,8 +114,9 @@ export {
   surfaceRulesSelecting,
 } from "./core/surface.js";
 export {
-  type BindingKind,
-  type DeclarationKind,
+  type Allowance,
+  BindingKind,
+  DeclarationKind,
   type ExportFix,
   type ExportRule,
   type GraphConfig,
@@ -87,10 +124,11 @@ export {
   type GraphOrphanRule,
   type GraphReachRule,
   type ImportProbe,
-  type ImportProbeTarget,
+  ImportProbeTarget,
   type ImportRule,
   type MemberRule,
-  type MemberSubject,
+  MemberSubject,
+  PatternList,
   type ResolveConfig,
   type ResolveScope,
   type StructureConfig,
@@ -100,6 +138,7 @@ export {
   ConfigInvalid,
   ImportUnresolved,
   PatternInvalid,
+  ReportUnavailable,
   ScopeInvalid,
 } from "./domain/architecture-error.js";
 export {
@@ -108,6 +147,30 @@ export {
   type MemberSite,
   type SourceFacts,
 } from "./domain/facts.js";
+export {
+  type ManifestLocator,
+  type ManifestPath,
+  type ManifestPosition,
+  renderManifestPath,
+} from "./domain/manifest-location.js";
+export {
+  CONFORMANCE_MEASURES,
+  type ConformanceMeasure,
+  decodeSnapshot,
+  type Snapshot,
+  SNAPSHOT_SCHEMA_ID,
+  SNAPSHOT_VERSION,
+  type SnapshotCampaign,
+  type SnapshotConcentration,
+  snapshotJsonSchema,
+  type SnapshotObjective,
+  type SnapshotPhase,
+  Snapshot as SnapshotSchema,
+  type SnapshotSector,
+  type SnapshotSlack,
+  type SnapshotVacancy,
+  type SnapshotViolation,
+} from "./domain/snapshot.js";
 export {
   fingerprintOf,
   formatMessage,
@@ -115,16 +178,89 @@ export {
   type ViolationKind,
 } from "./domain/violation.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 {
+  listPackageRoots,
+  listSourceFiles,
+  listWorkspaceProjects,
+  type PackagedLanguage,
+  type PackageRoot,
+  type WalkedLanguage,
+  type WorkspaceProject,
+} from "./infrastructure/walk.js";
+export {
+  type ExtensionContext,
+  type ExtensionRoute,
+  type LoadedExtension,
+  type PolicyExtension,
+} from "./load/extension.js";
 export { type LoadedPolicy, loadPolicy, type LoadPolicyInput } from "./load/policy.js";
-export { type LoweredRules, lowerManifest, type ProbeLanguage } from "./manifest/compile.js";
+export {
+  CONVENTIONS,
+  expandAliases,
+  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 ManifestExtension } from "./manifest/extension.js";
+export {
+  anchored,
+  type CaptureIndex,
+  type GlobCompilation,
+  globToRegExp,
+  globToRegexSource,
+  prefixed,
+} from "./manifest/glob.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,
+  type ManifestJsonSchemaOptions,
+  manifestNodeJsonSchema,
+} from "./manifest/json-schema.js";
 export {
   type DecodedManifest,
   decodeManifest,
+  type DecodeManifestOptions,
+  decodeManifestTree,
+  globsOf,
   type Manifest,
   type ManifestNode,
   Manifest as ManifestSchema,
+  SurfaceConvention,
 } from "./manifest/manifest.js";
 export { type FactExtractor } from "./ports/fact-extractor.js";
 export { type FileSystem } from "./ports/file-system.js";
@@ -134,3 +270,9 @@ export {
   type ModuleResolver,
   type ResolvedTarget,
 } from "./ports/module-resolver.js";
+export {
+  type Position,
+  type SyntaxMatch,
+  type SyntaxMatcher,
+  type SyntaxTree,
+} from "./ports/syntax-matcher.js";

package/src/infrastructure/file-system-fake.ts

@@ -10,5 +10,17 @@ export const makeFileSystemFake = (
   return {
     exists: (repoRelativePath) => paths.has(repoRelativePath),
     readText: (repoRelativePath) => contents[repoRelativePath] ?? null,
+    list: (repoRelativeDir) => {
+      const prefix = repoRelativeDir === "" ? "" : `${repoRelativeDir}/`;
+      return [
+        ...new Set(
+          [...paths]
+            .filter((one) => one.startsWith(prefix))
+            .map((one) => one.slice(prefix.length).split("/")[0] ?? ""),
+        ),
+      ]
+        .filter((one) => one !== "")
+        .sort();
+    },
   };
 };

package/src/infrastructure/file-system-live.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import * as path from "node:path";
 
 import type { FileSystem } from "../ports/file-system.js";
@@ -23,5 +23,12 @@ export const makeFileSystemLive = (repoRoot: string): FileSystem => {
         return null;
       }
     },
+    list: (repoRelativeDir) => {
+      try {
+        return readdirSync(path.resolve(repoRoot, repoRelativeDir)).sort();
+      } catch {
+        return [];
+      }
+    },
   };
 };

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" });