@adrkit/evaluator 0.1.0

package/src/rules/scope-hierarchy.ts

@@ -0,0 +1,108 @@
+/**
+ * @adrkit/evaluator — rule 7: scope-hierarchy (error).
+ *
+ * A `component` proposal that overlaps an APPLICABLE accepted `org` ADR whose assertion
+ * was GREEN on the supplied base input and FAILS on the supplied proposed input is an
+ * attributable contradiction ⇒ error (research §R5). Domain applicability is explicit:
+ * an org ADR with no domain is global; otherwise it applies only on exact domain
+ * equality. The evaluator itself compiles + evaluates the accepted assertion (it never
+ * accepts a precomputed verdict). Missing engine/source/base/proposed evidence is inert;
+ * a non-component proposal or one with no applicable org overlap passes.
+ */
+
+import type { Adr } from '@adrkit/core';
+import { aggregate, passResult, type SubResult } from './kernel.ts';
+import type { RuleContext } from './context.ts';
+import { compileAssertionForScope } from '../assertions/evaluate.ts';
+import { makeAssertionKey } from '../keys.ts';
+import { anyMatcherInert, resolveRecordTargets } from '../targets/canonical.ts';
+import { byCodeUnit } from '../compare.ts';
+import type { RuleResult } from '../types.ts';
+
+function domainApplies(orgRecord: Adr, proposal: Adr): boolean {
+  const orgDomain = orgRecord.frontmatter.domain;
+  if (orgDomain === undefined) return true; // org-with-no-domain is global
+  return orgDomain === proposal.frontmatter.domain;
+}
+
+export function evaluateScopeHierarchy(ctx: RuleContext): RuleResult {
+  const proposal = ctx.proposed;
+  if (proposal.frontmatter.scope !== 'component') {
+    return passResult('scope-hierarchy', 'scope-hierarchy.not-applicable-scope');
+  }
+
+  const proposalTargets = resolveRecordTargets(proposal, ctx.input.targetRegistry, ctx.input.targets, ctx.input.resolutionLog);
+  const subs: SubResult[] = [];
+  if (anyMatcherInert(proposalTargets)) {
+    subs.push({ status: 'inert', reason: 'scope-hierarchy.evidence-absent' });
+  }
+
+  const applicableOrgAdrs: Adr[] = [];
+  for (const record of ctx.acceptedRecords) {
+    if (record.frontmatter.scope !== 'org') continue;
+    if (!domainApplies(record, proposal)) continue;
+    const orgTargets = resolveRecordTargets(record, ctx.input.targetRegistry, ctx.input.targets, ctx.input.resolutionLog);
+    if (anyMatcherInert(orgTargets)) {
+      subs.push({ status: 'inert', reason: 'scope-hierarchy.evidence-absent' });
+    }
+    if ([...proposalTargets.targetKeys].some((key) => orgTargets.targetKeys.has(key))) {
+      applicableOrgAdrs.push(record);
+    }
+  }
+
+  if (applicableOrgAdrs.length === 0) {
+    return subs.length > 0
+      ? aggregate('scope-hierarchy', subs)
+      : passResult('scope-hierarchy', 'scope-hierarchy.ok');
+  }
+
+  const transitions: string[] = [];
+
+  for (const orgRecord of applicableOrgAdrs) {
+    for (const assertion of orgRecord.frontmatter.assertions) {
+      const key = makeAssertionKey(orgRecord.log, orgRecord.path, assertion.id);
+      const compiled = compileAssertionForScope(ctx, orgRecord, assertion);
+      if (!compiled.ok) {
+        const reason =
+          compiled.reason === 'engine-absent'
+            ? 'scope-hierarchy.engine-absent'
+            : 'scope-hierarchy.source-absent';
+        subs.push({ status: 'inert', reason });
+        continue;
+      }
+      const baseInput = ctx.input.scopeEvidence?.baseInputs?.[key]?.document;
+      if (baseInput === undefined) {
+        subs.push({ status: 'inert', reason: 'scope-hierarchy.base-input-absent' });
+        continue;
+      }
+      const proposedInput = ctx.input.assertionInputs.inputs[key]?.document;
+      if (proposedInput === undefined) {
+        subs.push({ status: 'inert', reason: 'scope-hierarchy.proposed-input-absent' });
+        continue;
+      }
+      const baseEval = compiled.evaluate(baseInput);
+      const proposedEval = compiled.evaluate(proposedInput);
+      if (!baseEval.ok || !proposedEval.ok) {
+        subs.push({ status: 'inert', reason: 'scope-hierarchy.evidence-absent' });
+        continue;
+      }
+      if (baseEval.pass && !proposedEval.pass) {
+        transitions.push(`${orgRecord.frontmatter.id}:${assertion.id}`);
+        subs.push({
+          status: 'fail',
+          reason: 'scope-hierarchy.contradicts-org-assertion',
+          finding: {
+            reason: 'scope-hierarchy.contradicts-org-assertion',
+            candidateAdr: proposal.frontmatter.id,
+            relatedAdr: orgRecord.frontmatter.id,
+            assertionKey: key,
+            message: `Proposal turns accepted org assertion "${orgRecord.frontmatter.id}:${assertion.id}" from green to red`,
+          },
+        });
+      }
+    }
+  }
+
+  if (subs.length === 0) return passResult('scope-hierarchy', 'scope-hierarchy.ok');
+  return aggregate('scope-hierarchy', subs, transitions.length > 0 ? { assertionTransitions: [...transitions].sort(byCodeUnit) } : undefined);
+}

package/src/rules/supersession-consistent.ts

@@ -0,0 +1,138 @@
+/**
+ * @adrkit/evaluator — rule 3: supersession-consistent (error).
+ *
+ * New deterministic reciprocity + cycle checks over the corpus snapshot (research
+ * §R3), reusing `buildAdrGraph` for EDGES ONLY. Reciprocity: `A supersedes B` iff
+ * `B.supersededBy === A`. `dangling-supersededBy` is owned exclusively by this rule
+ * (C2) and suppresses the redundant non-reciprocal finding for the same ref. Cycles
+ * in the supersedes relation fail with `cycle`. Exactly one aggregate result (C11).
+ */
+
+import { buildAdrGraph, type Adr } from '@adrkit/core';
+import { aggregate, passResult, type SubResult } from './kernel.ts';
+import type { RuleContext } from './context.ts';
+import type { RuleFinding, RuleResult } from '../types.ts';
+
+function hasSupersedesCycle(records: readonly Adr[]): boolean {
+  const graph = buildAdrGraph(records);
+  const adjacency = new Map<string, string[]>();
+  for (const edge of graph.edges) {
+    if (edge.kind !== 'supersedes') continue;
+    const list = adjacency.get(edge.from) ?? [];
+    list.push(edge.to);
+    adjacency.set(edge.from, list);
+  }
+  const WHITE = 0;
+  const GRAY = 1;
+  const BLACK = 2;
+  const color = new Map<string, number>();
+  const nodes = graph.nodes.map((node) => node.id);
+
+  function visit(node: string): boolean {
+    color.set(node, GRAY);
+    for (const next of adjacency.get(node) ?? []) {
+      const state = color.get(next) ?? WHITE;
+      if (state === GRAY) return true;
+      if (state === WHITE && visit(next)) return true;
+    }
+    color.set(node, BLACK);
+    return false;
+  }
+
+  for (const node of nodes) {
+    if ((color.get(node) ?? WHITE) === WHITE && visit(node)) return true;
+  }
+  return false;
+}
+
+export function evaluateSupersessionConsistent(ctx: RuleContext): RuleResult {
+  const records = ctx.corpusRecords;
+  const ids = new Set(records.map((record) => record.frontmatter.id));
+  const supersededByById = new Map<string, string>();
+  for (const record of records) {
+    if (record.frontmatter.supersededBy) {
+      supersededByById.set(record.frontmatter.id, record.frontmatter.supersededBy);
+    }
+  }
+
+  const subs: SubResult[] = [];
+  const seenPairs = new Set<string>();
+  const danglingRefs = new Set<string>();
+
+  // Dangling supersededBy — owned here, once per record.
+  for (const record of records) {
+    const target = record.frontmatter.supersededBy;
+    if (target && !ids.has(target)) {
+      danglingRefs.add(`${record.frontmatter.id}->${target}`);
+      const finding: RuleFinding = {
+        reason: 'supersession-consistent.dangling-superseded-by',
+        message: `supersededBy "${target}" does not resolve to a record in the corpus`,
+        adr: record.frontmatter.id,
+        candidateAdr: record.frontmatter.id,
+        relatedAdr: target,
+        recordPath: record.path,
+        field: 'supersededBy',
+        lowerLevel: { rule: 'dangling-supersededBy', path: record.path, id: record.frontmatter.id, field: 'supersededBy' },
+      };
+      subs.push({ status: 'fail', reason: 'supersession-consistent.dangling-superseded-by', finding });
+    }
+  }
+
+  function nonReciprocal(fromId: string, toId: string, path: string, field: 'supersedes' | 'supersededBy'): void {
+    const key = [fromId, toId].sort().join('|');
+    if (seenPairs.has(key)) return;
+    seenPairs.add(key);
+    const finding: RuleFinding = {
+      reason: 'supersession-consistent.non-reciprocal',
+      message: `supersedes/supersededBy between "${fromId}" and "${toId}" is not reciprocal`,
+      adr: fromId,
+      candidateAdr: fromId,
+      relatedAdr: toId,
+      recordPath: path,
+      field,
+      lowerLevel: { rule: 'non-reciprocal', path, id: fromId, field },
+    };
+    subs.push({ status: 'fail', reason: 'supersession-consistent.non-reciprocal', finding });
+  }
+
+  // A supersedes B ⇒ B.supersededBy === A.
+  for (const record of records) {
+    for (const target of record.frontmatter.supersedes) {
+      if (!ids.has(target)) continue; // orphan supersedes — owned by no-orphan-refs
+      if (supersededByById.get(target) !== record.frontmatter.id) {
+        nonReciprocal(record.frontmatter.id, target, record.path, 'supersedes');
+      }
+    }
+  }
+
+  // B.supersededBy === A ⇒ A.supersedes contains B.
+  const supersedesPairs = new Set<string>();
+  for (const record of records) {
+    for (const target of record.frontmatter.supersedes) {
+      supersedesPairs.add(`${record.frontmatter.id}=>${target}`);
+    }
+  }
+  for (const record of records) {
+    const target = record.frontmatter.supersededBy;
+    if (!target || !ids.has(target)) continue; // dangling handled above
+    if (danglingRefs.has(`${record.frontmatter.id}->${target}`)) continue;
+    if (!supersedesPairs.has(`${target}=>${record.frontmatter.id}`)) {
+      nonReciprocal(record.frontmatter.id, target, record.path, 'supersededBy');
+    }
+  }
+
+  if (hasSupersedesCycle(records)) {
+    subs.push({
+      status: 'fail',
+      reason: 'supersession-consistent.cycle',
+      finding: {
+        reason: 'supersession-consistent.cycle',
+        message: 'The supersedes relation contains a cycle',
+        lowerLevel: { rule: 'supersedes-cycle' },
+      },
+    });
+  }
+
+  if (subs.length === 0) return passResult('supersession-consistent');
+  return aggregate('supersession-consistent', subs);
+}

package/src/targets/canonical.ts

@@ -0,0 +1,114 @@
+/**
+ * @adrkit/evaluator — canonical target normalization + record resolution (T035, R4/ADR-0009).
+ *
+ * Resolves a record's `affects` matchers to a finite canonical target-id set, honoring
+ * ADR-0009 semantics: union non-negated matches, subtract matching negations, require
+ * at least one positive matcher (negation-only ⇒ empty), and apply a `repo` qualifier
+ * only when it equals the caller-supplied current resolution `log` (a different-repo
+ * qualifier contributes no local match). The current log is passed explicitly to every
+ * resolver port; it is never inferred from a record's source `log`.
+ */
+
+import type { Adr, AffectsType } from '@adrkit/core';
+import { canonicalTargetKey } from '../keys.ts';
+import { byCodeUnit } from '../compare.ts';
+import type {
+  CanonicalTargetId,
+  CanonicalTargetKey,
+  TargetInventorySnapshots,
+  TargetResolutionContext,
+  TargetResolutionRegistry,
+} from '../types.ts';
+
+/** Normalize a repo-relative path id to posix form (no leading `./`, no backslashes). */
+export function normalizePathId(path: string): string {
+  return path.replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+export function makeTargetId(kind: AffectsType, id: string): CanonicalTargetId {
+  return { kind, id: kind === 'path' ? normalizePathId(id) : id };
+}
+
+/** The outcome of resolving a single applied `affects` matcher. */
+export interface MatcherResolution {
+  readonly type: AffectsType;
+  readonly pattern: string;
+  readonly negate: boolean;
+  /** `resolved` includes a different-repo matcher (deterministic empty locally). */
+  readonly status: 'resolved' | 'inert-backing' | 'inert-resolver';
+  readonly ids: readonly CanonicalTargetId[];
+}
+
+export interface RecordTargetResolution {
+  /** Final, unique, canonically-ordered target ids (positive − negated). */
+  readonly targets: readonly CanonicalTargetId[];
+  readonly targetKeys: ReadonlySet<CanonicalTargetKey>;
+  /** Per-applied-matcher outcomes, so each matcher can be validated independently (C3, finding #2). */
+  readonly matchers: readonly MatcherResolution[];
+  readonly hasMatchers: boolean;
+  readonly hasPositiveMatcher: boolean;
+}
+
+/** True if any matcher could not be resolved (missing inventory or resolver port). */
+export function anyMatcherInert(resolution: RecordTargetResolution): boolean {
+  return resolution.matchers.some((matcher) => matcher.status !== 'resolved');
+}
+
+function sortedUnique(ids: Iterable<CanonicalTargetId>): CanonicalTargetId[] {
+  const byKey = new Map<CanonicalTargetKey, CanonicalTargetId>();
+  for (const id of ids) byKey.set(canonicalTargetKey(id), id);
+  return [...byKey.values()].sort((a, b) => byCodeUnit(canonicalTargetKey(a), canonicalTargetKey(b)));
+}
+
+/** Resolve one record's affects matchers against the registry + inventory. */
+export function resolveRecordTargets(
+  record: Adr,
+  registry: TargetResolutionRegistry,
+  inventory: TargetInventorySnapshots,
+  resolutionLog: string | undefined,
+): RecordTargetResolution {
+  const context: TargetResolutionContext = { ...(resolutionLog !== undefined ? { log: resolutionLog } : {}), inventory };
+  const positive = new Map<CanonicalTargetKey, CanonicalTargetId>();
+  const negated = new Set<CanonicalTargetKey>();
+  const matcherResolutions: MatcherResolution[] = [];
+  const matchers = record.frontmatter.affects;
+  let hasPositiveMatcher = false;
+
+  for (const matcher of matchers) {
+    const type = matcher.type;
+    if (!matcher.negate) hasPositiveMatcher = true;
+
+    // repo qualifier: a different-repo matcher applies to another repo and contributes no
+    // local match — it resolves deterministically to the empty set locally.
+    if (matcher.repo !== undefined && matcher.repo !== resolutionLog) {
+      matcherResolutions.push({ type, pattern: matcher.pattern, negate: matcher.negate, status: 'resolved', ids: [] });
+      continue;
+    }
+    const port = registry.get(type);
+    if (!port) {
+      matcherResolutions.push({ type, pattern: matcher.pattern, negate: matcher.negate, status: 'inert-resolver', ids: [] });
+      continue;
+    }
+    const resolution = port.resolve(matcher, context);
+    if (resolution.status === 'inert') {
+      matcherResolutions.push({ type, pattern: matcher.pattern, negate: matcher.negate, status: 'inert-backing', ids: [] });
+      continue;
+    }
+    matcherResolutions.push({ type, pattern: matcher.pattern, negate: matcher.negate, status: 'resolved', ids: resolution.ids });
+    for (const id of resolution.ids) {
+      const key = canonicalTargetKey(id);
+      if (matcher.negate) negated.add(key);
+      else positive.set(key, id);
+    }
+  }
+
+  const finalIds = [...positive.entries()].filter(([key]) => !negated.has(key)).map(([, id]) => id);
+  const targets = sortedUnique(finalIds);
+  return {
+    targets,
+    targetKeys: new Set(targets.map(canonicalTargetKey)),
+    matchers: matcherResolutions,
+    hasMatchers: matchers.length > 0,
+    hasPositiveMatcher,
+  };
+}

package/src/targets/package.ts

@@ -0,0 +1,41 @@
+/**
+ * @adrkit/evaluator — built-in `package` target resolver.
+ *
+ * Reuses core's neutral `matchPackagePattern` grammar (name + optional semver range)
+ * over a complete dependency inventory, per dependency — without copying the grammar
+ * or importing semver directly (that stays a core-internal concern). A missing
+ * `dependencies` inventory is inert (backing-absent); an unparseable pattern resolves
+ * to the empty set. Pure.
+ */
+
+import { matchPackagePattern, parsePackagePattern } from '@adrkit/core';
+import { makeTargetId } from './canonical.ts';
+import type { AffectsMatcher, TargetResolution, TargetResolutionContext, TargetResolverPort } from '../types.ts';
+
+export function createPackageTargetResolver(): TargetResolverPort {
+  return {
+    type: 'package',
+    resolve(matcher: AffectsMatcher, context: TargetResolutionContext): TargetResolution {
+      const inventory = context.inventory.dependencies;
+      if (inventory === undefined) {
+        return { status: 'inert', ids: [], reason: 'affects-resolvable.backing-absent' };
+      }
+      if (!parsePackagePattern(matcher.pattern)) {
+        return { status: 'resolved', ids: [], reason: 'affects-resolvable.zero-targets' };
+      }
+      const ids = inventory
+        .filter(
+          (dependency) =>
+            matchPackagePattern(matcher.pattern, [
+              { name: dependency.name, version: dependency.version ?? '0.0.0-unversioned' },
+            ]).matched,
+        )
+        .map((dependency) => makeTargetId('package', dependency.name));
+      return {
+        status: 'resolved',
+        ids,
+        reason: ids.length > 0 ? 'affects-resolvable.ok' : 'affects-resolvable.zero-targets',
+      };
+    },
+  };
+}

package/src/targets/path.ts

@@ -0,0 +1,32 @@
+/**
+ * @adrkit/evaluator — built-in `path` target resolver.
+ *
+ * Reuses core's neutral repo-relative path-glob primitive (`matchPathPattern`) over a
+ * complete tracked-path inventory — it never copies the grammar. A missing
+ * `trackedPaths` inventory is inert (backing-absent); a bad/leading-slash pattern
+ * resolves to the empty set (⇒ affects-resolvable zero-targets, not a throw). Pure.
+ */
+
+import { matchPathPattern } from '@adrkit/core';
+import { makeTargetId } from './canonical.ts';
+import type { AffectsMatcher, TargetResolution, TargetResolutionContext, TargetResolverPort } from '../types.ts';
+
+export function createPathTargetResolver(): TargetResolverPort {
+  return {
+    type: 'path',
+    resolve(matcher: AffectsMatcher, context: TargetResolutionContext): TargetResolution {
+      const inventory = context.inventory.trackedPaths;
+      if (inventory === undefined) {
+        return { status: 'inert', ids: [], reason: 'affects-resolvable.backing-absent' };
+      }
+      const ids = inventory
+        .filter((path) => matchPathPattern(matcher.pattern, [path]).matched)
+        .map((path) => makeTargetId('path', path));
+      return {
+        status: 'resolved',
+        ids,
+        reason: ids.length > 0 ? 'affects-resolvable.ok' : 'affects-resolvable.zero-targets',
+      };
+    },
+  };
+}

package/src/targets/registry.ts

@@ -0,0 +1,23 @@
+/**
+ * @adrkit/evaluator — target resolver registry.
+ *
+ * A registry is a pure lookup from `AffectsType` to a deterministic resolver port.
+ * A lookup miss makes the corresponding matcher inert (`resolver-absent`), never a
+ * failure. Ports are built only by trusted composition code — never selected by JSON.
+ */
+
+import type { AffectsType } from '@adrkit/core';
+import type { TargetResolutionRegistry, TargetResolverPort } from '../types.ts';
+
+export function createTargetResolutionRegistry(
+  ports: readonly TargetResolverPort[],
+): TargetResolutionRegistry {
+  const byType = new Map<AffectsType, TargetResolverPort>();
+  for (const port of ports) byType.set(port.type, port);
+  return { get: (type: AffectsType) => byType.get(type) };
+}
+
+/** A registry with no resolvers — every target matcher is `resolver-absent` inert. */
+export const emptyTargetResolutionRegistry: TargetResolutionRegistry = {
+  get: () => undefined,
+};