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

package/src/core/slack.ts

@@ -0,0 +1,135 @@
+import type { Allowance } from "../domain/architecture-config.js";
+import type { ResolvedTarget } from "../ports/module-resolver.js";
+import { vacantNodesOf } from "./coverage.js";
+import type { CompiledImportRule } from "./imports.js";
+import { firstFromMatch, matchesAny } from "./patterns.js";
+
+// Coverage says how many files an allowlist reaches. This is the other
+// question about an allowlist: how much of it is used. A manifest inferred
+// from today's edges reaches every file and constrains nothing, so coverage
+// alone reads as complete while the policy is pure permission; slack is the
+// number that tells the two apart. It is also the signature of an allowlist
+// widened to make a build green — an entry nothing imports through.
+
+// An edge the host resolved: the importer, and what the specifier became.
+export type ObservedEdge = {
+  readonly importer: string;
+  readonly target: ResolvedTarget;
+};
+
+// An allowance no observed edge uses. The same shape the lowering recorded,
+// minus the compiled pattern nobody wrote. When the entry arrived through
+// `use`, `node` is the fragment's name — the line to delete is in `defs` —
+// and `of` says how many nodes wrote the reference that carried it.
+export type Slack = Pick<Allowance, "node" | "kind" | "entry"> & {
+  readonly fragment?: string;
+  readonly of?: number;
+};
+
+// A fragment entry used at some of the nodes it was granted to and not the
+// rest. At the fragment level it is not slack — there is no line nobody
+// needs — but it is a per-file permission written as a many-node allowance,
+// which is what an allowlist widened to make one build green looks like.
+export type Concentration = Pick<Allowance, "kind" | "entry"> & {
+  readonly fragment: string;
+  readonly usedAt: number;
+  readonly of: number;
+};
+
+export type SlackReport = {
+  readonly slack: ReadonlyArray<Slack>;
+  readonly concentration: ReadonlyArray<Concentration>;
+};
+
+const keyOf = (one: Pick<Allowance, "node" | "kind" | "entry">): string =>
+  `${one.node} ${one.kind} ${one.entry}`;
+
+// Whether one edge, from a file this rule selects, passes through this entry.
+const uses = (allowance: Allowance, captures: RegExpExecArray, target: ResolvedTarget): boolean => {
+  if (allowance.kind === "external") {
+    return target.kind === "external" && target.package === allowance.entry;
+  }
+  return allowance.pattern !== undefined && matchesAny([allowance.pattern], captures, target.path);
+};
+
+// One entry as one place wrote it: a node that wrote the line, or a fragment
+// that N nodes pulled in with `use`. Keyed by that place, so a fragment's
+// entry is reported once however many nodes reference it.
+type Declared = {
+  readonly node: string;
+  readonly kind: Allowance["kind"];
+  readonly entry: string;
+  readonly fragment: string | undefined;
+  // The nodes that declared it, vacant ones excluded — every allowance on a
+  // vacant node is unused by construction, and is vacancy, not slack.
+  readonly at: Set<string>;
+};
+
+const groupKeyOf = (one: Allowance): string =>
+  one.fragment === undefined
+    ? `node ${one.node} ${one.kind} ${one.entry}`
+    : `use ${one.fragment} ${one.kind} ${one.entry}`;
+
+// Every allowance the rules carry that no edge uses, in the order the manifest
+// declared them. An entry is inherited by every descendant's rule and written
+// once, so it is keyed by where it was written: an import anywhere under the
+// declaring node is a use. An entry that arrived through `use` is keyed by
+// the fragment, and is slack only when no node it was granted to uses it;
+// used at some and not others, it is reported as concentration instead. A
+// vacant node — one whose allowlist selects no walked file — contributes
+// nothing to either.
+export const slackOf = (
+  rules: ReadonlyArray<CompiledImportRule>,
+  edges: ReadonlyArray<ObservedEdge>,
+  files: ReadonlyArray<string>,
+): SlackReport => {
+  const vacant = vacantNodesOf(rules, files);
+
+  const declared = new Map<string, Declared>();
+  for (const rule of rules) {
+    for (const allowance of rule.allowances) {
+      if (vacant.has(allowance.node)) continue;
+      const key = groupKeyOf(allowance);
+      const group = declared.get(key) ?? {
+        node: allowance.fragment ?? allowance.node,
+        kind: allowance.kind,
+        entry: allowance.entry,
+        fragment: allowance.fragment,
+        at: new Set<string>(),
+      };
+      group.at.add(allowance.node);
+      declared.set(key, group);
+    }
+  }
+
+  // Which (node, kind, entry) some edge passes through.
+  const used = new Set<string>();
+  for (const edge of edges) {
+    for (const rule of rules) {
+      if (rule.allowances.length === 0) continue;
+      const captures = firstFromMatch(rule, edge.importer);
+      if (captures === null) continue;
+      for (const allowance of rule.allowances) {
+        if (uses(allowance, captures, edge.target)) used.add(keyOf(allowance));
+      }
+    }
+  }
+
+  const slack: Array<Slack> = [];
+  const concentration: Array<Concentration> = [];
+  for (const group of declared.values()) {
+    const { entry, kind } = group;
+    const usedAt = [...group.at].filter((node) => used.has(keyOf({ node, kind, entry }))).length;
+    if (group.fragment === undefined) {
+      if (usedAt === 0) slack.push({ node: group.node, kind, entry });
+      continue;
+    }
+    const of = group.at.size;
+    if (usedAt === 0) {
+      slack.push({ node: group.node, kind, entry, fragment: group.fragment, of });
+    } else if (usedAt < of) {
+      concentration.push({ fragment: group.fragment, kind, entry, usedAt, of });
+    }
+  }
+  return { slack, concentration };
+};

package/src/core/structure.ts

@@ -191,17 +191,22 @@ const resolveSibling = (folder: string, relative: string): string => {
   return segments.join("/");
 };
 
-export const requiredSiblingsOf = (
-  rule: CompiledStructureParity,
+// The paths a list of `requires` templates names beside a file. Shared with
+// the campaigns evaluator, whose `requires` term asks the same question.
+export const siblingsOf = (
+  templates: ReadonlyArray<string>,
   file: string,
 ): ReadonlyArray<string> => {
   const base = baseOf(basenameOf(file));
   const folder = dirnameOf(file);
-  return rule.requires.map((template) =>
-    resolveSibling(folder, template.replaceAll("{base}", base)),
-  );
+  return templates.map((template) => resolveSibling(folder, template.replaceAll("{base}", base)));
 };
 
+export const requiredSiblingsOf = (
+  rule: CompiledStructureParity,
+  file: string,
+): ReadonlyArray<string> => siblingsOf(rule.requires, file);
+
 type NamingMatch = {
   readonly subject: string;
   readonly expected: string | null;

package/src/domain/architecture-config.ts

@@ -16,7 +16,7 @@ const PatternList = Schema.Union([Schema.String, Schema.Array(Schema.String)]);
 // importer path. `to` is the target in one of three forms, and the form is its
 // dependency kind: a repo-relative resolved path is `local`, `{ external }`
 // names a third-party package, `{ builtin }` names a runtime module.
-const ImportProbeTarget = Schema.Union([
+export const ImportProbeTarget = Schema.Union([
   Schema.String,
   Schema.Struct({ external: Schema.String }),
   Schema.Struct({ builtin: Schema.String }),
@@ -27,6 +27,28 @@ const ImportProbe = Schema.Struct({
   to: ImportProbeTarget,
 });
 
+// One entry of an `imports` allowlist, as the author wrote it and where. An
+// allowlist rule compiles its entries into `toNot` patterns and `externals`
+// names, which is all evaluation needs; this is the other direction — from a
+// pattern back to the line in the manifest that put it there — so a report
+// can say which line no import uses. Slack is the signature of an allowlist
+// widened to make a build green, and it is only visible with the entry kept.
+export const Allowance = Schema.Struct({
+  // The manifest node that declared the entry, as rule names name nodes.
+  node: Schema.String,
+  // `allow` is a path glob; `external` is a package name.
+  kind: Schema.Literals(["allow", "external"]),
+  // The entry as written, after alias expansion.
+  entry: Schema.String,
+  // For an `allow`: the compiled target pattern, as `toNot` carries it.
+  pattern: Schema.optionalKey(Schema.String),
+  // The `defs` fragment the entry arrived through, when the node wrote
+  // `use: <name>` rather than the entry itself. Slack is attributed to the
+  // fragment then: the node's authors wrote one word, and the line to delete
+  // is in `defs`.
+  fragment: Schema.optionalKey(Schema.String),
+});
+
 export const ImportRule = Schema.Struct({
   name: Schema.String,
   message: Schema.String,
@@ -35,6 +57,9 @@ export const ImportRule = Schema.Struct({
   fromNot: Schema.optionalKey(PatternList),
   to: Schema.optionalKey(PatternList),
   toNot: Schema.optionalKey(PatternList),
+  // Where each `toNot` pattern and `externals` name came from, for an
+  // allowlist lowered from a manifest. A hand-written rule carries none.
+  allowances: Schema.optionalKey(Schema.Array(Allowance)),
   // Third-party packages this rule permits, by package name. An external
   // target is judged by its package, never by where the language's resolver
   // happened to find it on disk — `to`/`toNot` patterns are for the
@@ -270,6 +295,178 @@ export const GraphConfig = Schema.Struct({
   reach: Schema.optionalKey(Schema.Array(GraphReachRule)),
 });
 
+// A campaign: a migration tracked as an object in the repository. Where a
+// rule says what may never happen, a campaign names a pattern the code is
+// moving away from, ledgers every place it still occurs, and refuses to let
+// the count go up unrecorded. Lowered from the manifest's `campaigns` list
+// with its globs resolved; the detector below is what the evaluator compiles.
+
+// What a hit is: a whole file, a named declaration in it, or one matched
+// expression. The unit decides what a term from another level means (a
+// file-level term in a declaration campaign is a filter; a declaration-level
+// term in a file campaign is existential) and what the fingerprint anchors on.
+export const CampaignUnit = Schema.Literals(["file", "declaration", "match"]);
+
+// The detector's leaf terms. Every pattern is a regular-expression source,
+// as everywhere else in this config; the manifest writes globs and lowering
+// translates them. Each term answers at one level — `path`, `imports`,
+// `requires`, `content` and a boolean `fn` about the file; `exports` and
+// `members` about a declaration; `syntax` and a listing `fn` about a match.
+const PathTerm = Schema.Struct({
+  file: PatternList,
+  fileNot: Schema.optionalKey(PatternList),
+  // With `convention`: which capture group of `file` holds the name being
+  // judged, and the shape it must have for the term to hold.
+  subject: Schema.optionalKey(Schema.Finite),
+  convention: Schema.optionalKey(Schema.String),
+});
+export type PathTerm = (typeof PathTerm)["Type"];
+
+const ImportsTerm = Schema.Struct({
+  // Where an edge of the file must resolve to: a path pattern, a package
+  // name, or a builtin. Holds when at least one edge does.
+  resolves: ImportProbeTarget,
+  // Names that must be pulled across that edge; omit for any binding.
+  symbols: Schema.optionalKey(Schema.Array(Schema.String)),
+});
+export type ImportsTerm = (typeof ImportsTerm)["Type"];
+
+const ExportsTerm = Schema.Struct({
+  name: Schema.optionalKey(PatternList),
+  kinds: Schema.optionalKey(Schema.Array(BindingKind)),
+  declares: Schema.optionalKey(Schema.Array(DeclarationKind)),
+  reexport: Schema.optionalKey(Schema.Boolean),
+});
+export type ExportsTerm = (typeof ExportsTerm)["Type"];
+
+const MembersTerm = Schema.Struct({
+  subject: MemberSubject,
+  name: Schema.optionalKey(PatternList),
+  in: Schema.optionalKey(PatternList),
+  declares: Schema.optionalKey(Schema.Array(DeclarationKind)),
+});
+export type MembersTerm = (typeof MembersTerm)["Type"];
+
+const ContentTerm = Schema.Struct({ regex: Schema.String });
+type ContentTerm = (typeof ContentTerm)["Type"];
+
+// How a metavariable of a syntax rule is narrowed: by the text it captured,
+// or by what the identifier at its root is bound to — the module it was
+// imported from and the name it was imported as.
+const BindingNarrowing = Schema.Struct({
+  resolves: ImportProbeTarget,
+  member: Schema.optionalKey(Schema.Array(Schema.String)),
+});
+
+const CaptureNarrowing = Schema.Struct({
+  regex: Schema.optionalKey(Schema.String),
+  binding: Schema.optionalKey(BindingNarrowing),
+});
+
+const SyntaxTerm = Schema.Struct({
+  // The engine's rule object, carried opaquely: the matcher validates it.
+  rule: Schema.Unknown,
+  where: Schema.optionalKey(Schema.Record(Schema.String, CaptureNarrowing)),
+});
+export type SyntaxTerm = (typeof SyntaxTerm)["Type"];
+
+// A pattern no parser of ours sees, reported by another program: a type
+// error, another linter's finding. Exactly one of `command` (run from the
+// repository root, once per process) and `file` (written by an earlier
+// step), each a list — the manifest's one string lowered to a list of one —
+// read as one report. Each diagnostic on a file is a match anchored on the
+// declaration at its position, keyed by its code and a hash of its message.
+export const ReportFormat = Schema.Literals(["tsc", "eslint", "oxlint", "regex"]);
+
+const ReportTerm = Schema.Struct({
+  command: Schema.optionalKey(Schema.Array(Schema.String)),
+  file: Schema.optionalKey(Schema.Array(Schema.String)),
+  format: ReportFormat,
+  // `regex` only: named groups `file`, `line`, and optionally `column`,
+  // `code`, `message`.
+  pattern: Schema.optionalKey(Schema.String),
+  // The codes the term speaks to; omit for every one.
+  codes: Schema.optionalKey(Schema.Array(Schema.String)),
+  codesNot: Schema.optionalKey(Schema.Array(Schema.String)),
+});
+export type ReportTerm = (typeof ReportTerm)["Type"];
+
+export type Detector =
+  | { readonly all: ReadonlyArray<Detector> }
+  | { readonly any: ReadonlyArray<Detector> }
+  | { readonly not: Detector }
+  | { readonly path: PathTerm }
+  | { readonly imports: ImportsTerm }
+  | { readonly exports: ExportsTerm }
+  | { readonly members: MembersTerm }
+  | { readonly requires: ReadonlyArray<string> }
+  | { readonly content: ContentTerm }
+  | { readonly syntax: SyntaxTerm }
+  | { readonly report: ReportTerm }
+  // `module#export`, resolved by the host before the policy loads.
+  | { readonly fn: string };
+
+const DetectorRef = Schema.suspend((): Schema.Codec<Detector> => Detector);
+
+export const Detector = 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 }),
+]);
+
+// One diagnostic a probe stands in for, positions one-based as a tool
+// prints them.
+export const ProbeDiagnostic = Schema.Struct({
+  line: Schema.Finite,
+  column: Schema.optionalKey(Schema.Finite),
+  code: Schema.optionalKey(Schema.String),
+  message: Schema.optionalKey(Schema.String),
+});
+
+// A source the campaign is proven against: the path it would have, its text
+// when a term needs one, the target of each of its edges (in place of the live
+// resolver), the files beside it (in place of the file system) and the
+// diagnostics reported on it (in place of the report source).
+export 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)),
+});
+
+export const CampaignRule = Schema.Struct({
+  // `campaign/<id>`, the rule name a violation carries.
+  name: Schema.String,
+  id: Schema.String,
+  title: Schema.optionalKey(Schema.String),
+  // The `how`: what a reader at a hit does about it.
+  message: Schema.String,
+  why: Schema.String,
+  owner: Schema.optionalKey(Schema.String),
+  scope: PatternList,
+  unit: CampaignUnit,
+  detect: Detector,
+  probes: Schema.Struct({
+    fires: Schema.Array(CampaignProbe),
+    ignores: Schema.Array(CampaignProbe),
+  }),
+  // Milliseconds without progress after which the campaign is stalled.
+  staleAfter: Schema.Finite,
+  // What `check` demands once the count is zero: keep the campaign as a
+  // guard against recurrence, or remove it from the manifest.
+  onComplete: Schema.Literals(["keep", "remove"]),
+});
+
 const PathProbe = Schema.Struct({ path: Schema.String });
 
 // The file taxonomy, as three questions rather than one nested tree.
@@ -336,6 +533,7 @@ const StructureConfig = Schema.Struct({
   naming: Schema.optionalKey(Schema.Array(StructureNaming)),
 });
 
+export type Allowance = (typeof Allowance)["Type"];
 export type ImportRule = (typeof ImportRule)["Type"];
 export type ResolveConfig = (typeof ResolveConfig)["Type"];
 export type ResolveScope = (typeof ResolveScope)["Type"];
@@ -361,6 +559,12 @@ export type StructureRoot = (typeof StructureRoot)["Type"];
 export type StructureFolder = (typeof StructureFolder)["Type"];
 export type StructureParity = (typeof StructureParity)["Type"];
 export type StructureNaming = (typeof StructureNaming)["Type"];
+export type CampaignUnit = (typeof CampaignUnit)["Type"];
+export type CampaignProbe = (typeof CampaignProbe)["Type"];
+export type ProbeDiagnostic = (typeof ProbeDiagnostic)["Type"];
+export type ReportFormat = (typeof ReportFormat)["Type"];
+export type CampaignRule = (typeof CampaignRule)["Type"];
+export type CaptureNarrowing = (typeof CaptureNarrowing)["Type"];
 
 // The file pattern an open folder's layout rule carries: it admits any name,
 // so it claims the folder without policing it. Coverage counts it apart.

package/src/domain/architecture-error.ts

@@ -57,3 +57,33 @@ export class ImportUnresolved extends Schema.TaggedErrorClass<ImportUnresolved>(
     return `${this.fromFile} imports "${this.specifier}", which does not resolve: ${this.detail}`;
   }
 }
+
+// A `report` term whose source cannot be read: a command that could not be
+// spawned, or a file that is not there. The live source raises it once per
+// spec and keeps it, as it would have kept the report, so a lint over eight
+// hundred files does not attempt the spawn eight hundred times; the plugin
+// catches it and reports it once. The message says what to do, because a
+// command is forked from whichever process asks — the CLI, or oxlint with
+// the plugin loaded, which is the linter itself — and Linux's default
+// overcommit heuristic refuses to fork a process holding one mapping larger
+// than RAM and swap, which the linter's AST buffers become mid-lint.
+export class ReportUnavailable extends Schema.TaggedErrorClass<ReportUnavailable>(
+  "ReportUnavailable",
+)("ReportUnavailable", {
+  // "command" or "file", and the value as authored.
+  kind: Schema.Literals(["command", "file"]),
+  source: Schema.String,
+  detail: Schema.String,
+}) {
+  override get message(): string {
+    return this.kind === "command"
+      ? `the report command \`${this.source}\` could not be run: ${this.detail}. The command ` +
+          `is forked from the process that asks for the report — \`architecture check\`, or ` +
+          `oxlint with the plugin loaded, which is the linter itself, and Linux can refuse to ` +
+          `fork the linter once it holds more memory than the machine could back. A report an ` +
+          `earlier step writes, named by \`file:\` instead of \`command:\`, is the form for CI ` +
+          `and the editor.`
+      : `the report file ${this.source} cannot be read: ${this.detail}. A \`report\` term's ` +
+          `\`file\` is written by an earlier step; run that first, or name a \`command\`.`;
+  }
+}

package/src/domain/facts.ts

@@ -1,15 +1,20 @@
 import type { BindingKind, DeclarationKind, MemberSubject } from "./architecture-config.js";
 
-// What a policy can know about one source file, read once. Both adapters
-// produce this vocabulary — the plugin from oxlint's syntax tree, the CLI from
-// TypeScript's — which is what keeps them answerable to the same core rather
-// than to each other. A rule is evaluated against these and nothing else.
+// What a policy can know about one source file, read once. A language pack
+// produces this vocabulary out of its syntax tree, and both hosts read it —
+// which is what keeps them answerable to the same core rather than to each
+// other. A rule is evaluated against these and nothing else.
 
 // One name pulled across one import edge: `import { makeCommandBus } from "…"`
 // is a single binding, and so is the `Effect` in `import { Effect } from "effect"`.
 export type Binding = {
   readonly symbol: string;
   readonly kind: BindingKind;
+  // The name the binding is known by in the importing file — `C` for
+  // `import { Component as C }`, `React` for a default import — which is how
+  // an identifier in the file's own syntax is traced back to the module it
+  // came from. Absent for a form that binds no name.
+  readonly local?: string;
 };
 
 // One declared or called name. For `members`, the declaration it is written in

package/src/domain/manifest-location.ts

@@ -0,0 +1,41 @@
+// Where in the manifest file a value was written. A decode error that names a
+// path is something the reader has to find; one that names a line is something
+// an editor can jump to. The host that read the file knows its lines; the
+// decoder knows the path — the locator is how the second asks the first.
+
+// A path into the manifest as the decoder sees it: object keys and array
+// indices, root first.
+export type ManifestPath = ReadonlyArray<PropertyKey>;
+
+export type ManifestPosition = {
+  // 1-based, as editors count.
+  readonly line: number;
+  readonly column: number;
+  // The file the position is in, when it is not the manifest itself: a
+  // manifest assembled from several files through `include` answers with the
+  // included file's path, relative to the manifest's own directory. Absent
+  // for a position in the manifest file.
+  readonly file?: string | undefined;
+};
+
+// Answers with the position of the value at `path`, or the nearest ancestor
+// that exists when the path names something the file does not contain (a
+// missing key), or `null` when the source has no positions to give.
+export type ManifestLocator = (path: ManifestPath) => ManifestPosition | null;
+
+const isIdentifier = (key: string): boolean => /^[A-Za-z_$][\w$]*$/.test(key);
+
+// `tree["~/core/"].members[0].subject` — dotted where a key reads as a name,
+// bracketed where it does not, so a node key that is a path pattern stays
+// legible.
+export const renderManifestPath = (path: ManifestPath): string =>
+  path.length === 0
+    ? "(root)"
+    : path
+        .map((segment, index) => {
+          if (typeof segment === "number") return `[${String(segment)}]`;
+          const key = String(segment);
+          if (isIdentifier(key)) return index === 0 ? key : `.${key}`;
+          return `[${JSON.stringify(key)}]`;
+        })
+        .join("");