@adrkit/core 0.1.0

package/src/affects/index.ts

@@ -0,0 +1,240 @@
+import type { Adr } from '../schema/adr.schema.ts';
+import { sortFindings, type Finding, type FindingSeverity } from '../validate/findings.ts';
+import type { CatalogSnapshot } from './catalog.ts';
+import { isAlwaysInertType, matchEntityPattern } from './inert.ts';
+import { matchPackagePattern, type ChangedDependency } from './matchers/package.ts';
+import { matchPathPattern } from './matchers/path.ts';
+
+export type { CatalogPort, CatalogSnapshot, CatalogSnapshotEntity, EntityId } from './catalog.ts';
+export {
+  deriveChangedDependenciesFromBunLockDiff,
+  matchPackagePattern,
+  parsePackagePattern,
+  type ChangedDependency,
+  type PackageMatcherResult,
+  type ParsedPackagePattern,
+} from './matchers/package.ts';
+// Neutral repo-relative path-glob primitive. Exposed so `@adrkit/evaluator` can reuse
+// the exact matcher grammar for `path` target resolution instead of duplicating it
+// (research §R4). Evaluator-specific target-registry concepts stay out of core.
+export { matchPathPattern, type PathMatcherResult } from './matchers/path.ts';
+
+export interface ResolutionSnapshots {
+  changedDependencies?: readonly ChangedDependency[];
+  catalog?: CatalogSnapshot;
+}
+
+export interface ResolveAffectsInput {
+  records: readonly Adr[];
+  changedFiles: readonly string[];
+  snapshots?: ResolutionSnapshots;
+  log?: string;
+}
+
+export interface FiredMatcher {
+  type: string;
+  pattern: string;
+}
+
+export interface AffectsMatch {
+  recordId: string;
+  firedMatchers: FiredMatcher[];
+}
+
+export interface ResolveAffectsResult {
+  matches: AffectsMatch[];
+  findings: Finding[];
+}
+
+type Matcher = Adr['frontmatter']['affects'][number] & {
+  type: string;
+  pattern: string;
+  repo?: string;
+  negate?: boolean;
+};
+
+interface MatcherEvaluation {
+  matched: boolean;
+  findings: Finding[];
+}
+
+function compareFiredMatcher(a: FiredMatcher, b: FiredMatcher): number {
+  return a.type.localeCompare(b.type) || a.pattern.localeCompare(b.pattern);
+}
+
+function uniqueSortedFiredMatchers(matchers: readonly FiredMatcher[]): FiredMatcher[] {
+  const byKey = new Map<string, FiredMatcher>();
+  for (const matcher of matchers) {
+    byKey.set(`${matcher.type}\0${matcher.pattern}`, matcher);
+  }
+  return [...byKey.values()].sort(compareFiredMatcher);
+}
+
+function affectsFinding(
+  record: Adr,
+  matcher: Matcher,
+  rule: string,
+  severity: FindingSeverity,
+  message: string,
+): Finding {
+  return {
+    rule,
+    severity,
+    message,
+    id: record.frontmatter.id,
+    path: record.path,
+    field: `affects.${matcher.type}`,
+    pattern: matcher.pattern,
+  };
+}
+
+function matcherAppliesToLog(matcher: Matcher, log: string | undefined): boolean {
+  return !matcher.repo || matcher.repo === log;
+}
+
+function evaluateMatcher(
+  record: Adr,
+  matcher: Matcher,
+  changedFiles: readonly string[],
+  snapshots: ResolutionSnapshots | undefined,
+): MatcherEvaluation {
+  if (matcher.type === 'path') {
+    const result = matchPathPattern(matcher.pattern, changedFiles);
+    if (result.badPattern) {
+      return {
+        matched: false,
+        findings: [
+          affectsFinding(
+            record,
+            matcher,
+            'affects-bad-pattern',
+            'warn',
+            result.badPattern === 'leading-slash'
+              ? `Path matcher "${matcher.pattern}" must be repo-relative and must not start with "/".`
+              : `Path matcher "${matcher.pattern}" is not a valid glob pattern.`,
+          ),
+        ],
+      };
+    }
+    return { matched: result.matched, findings: [] };
+  }
+
+  if (matcher.type === 'package') {
+    const result = matchPackagePattern(matcher.pattern, snapshots?.changedDependencies);
+    if (result.unresolvable) {
+      return {
+        matched: false,
+        findings: [
+          affectsFinding(
+            record,
+            matcher,
+            'affects-unresolvable',
+            'info',
+            `Package matcher "${matcher.pattern}" requires a changed-dependency snapshot and is inert.`,
+          ),
+        ],
+      };
+    }
+    if (result.badPattern) {
+      return {
+        matched: false,
+        findings: [
+          affectsFinding(
+            record,
+            matcher,
+            'affects-bad-pattern',
+            'warn',
+            `Package matcher "${matcher.pattern}" must be "name" or "name@<valid semver range>".`,
+          ),
+        ],
+      };
+    }
+    return { matched: result.matched, findings: [] };
+  }
+
+  if (matcher.type === 'entity') {
+    const result = matchEntityPattern(matcher.pattern, changedFiles, snapshots?.catalog);
+    if (result.unresolvable) {
+      return {
+        matched: false,
+        findings: [
+          affectsFinding(
+            record,
+            matcher,
+            'affects-unresolvable',
+            'info',
+            `Entity matcher "${matcher.pattern}" has no catalog snapshot and is inert.`,
+          ),
+        ],
+      };
+    }
+    return { matched: result.matched, findings: [] };
+  }
+
+  if (isAlwaysInertType(matcher.type)) {
+    return {
+      matched: false,
+      findings: [
+        affectsFinding(
+          record,
+          matcher,
+          'affects-unresolvable',
+          'info',
+          `${matcher.type} matcher "${matcher.pattern}" has no backing snapshot in this phase and is inert.`,
+        ),
+      ],
+    };
+  }
+
+  // TODO(phase: schema-evolution): Allow unknown affects `type` values to pass
+  // validation as a warning so this forward-compat branch is reachable for real records.
+  // Requires an ADR-0002/0009 schema decision.
+  return {
+    matched: false,
+    findings: [
+      affectsFinding(
+        record,
+        matcher,
+        'affects-unknown-type',
+        'warn',
+        `Affects matcher type "${matcher.type}" is not recognized by this adrkit version and was ignored.`,
+      ),
+    ],
+  };
+}
+
+export function resolveAffects(input: ResolveAffectsInput): ResolveAffectsResult {
+  const matches: AffectsMatch[] = [];
+  const findings: Finding[] = [];
+
+  for (const record of input.records) {
+    const firedMatchers: FiredMatcher[] = [];
+    let suppressed = false;
+
+    for (const matcher of (record.frontmatter.affects ?? []) as readonly Matcher[]) {
+      if (!matcherAppliesToLog(matcher, input.log)) continue;
+
+      const result = evaluateMatcher(record, matcher, input.changedFiles, input.snapshots);
+      findings.push(...result.findings);
+
+      if (!result.matched) continue;
+      if (matcher.negate) {
+        suppressed = true;
+      } else {
+        firedMatchers.push({ type: matcher.type, pattern: matcher.pattern });
+      }
+    }
+
+    if (!suppressed && firedMatchers.length > 0) {
+      matches.push({
+        recordId: record.frontmatter.id,
+        firedMatchers: uniqueSortedFiredMatchers(firedMatchers),
+      });
+    }
+  }
+
+  return {
+    matches: matches.sort((a, b) => a.recordId.localeCompare(b.recordId)),
+    findings: sortFindings(findings),
+  };
+}

package/src/affects/inert.ts

@@ -0,0 +1,63 @@
+import picomatch from 'picomatch';
+import type { CatalogSnapshot, EntityId } from './catalog.ts';
+
+export type InertMatcherType = 'entity' | 'resource' | 'api' | 'data';
+
+export interface EntityMatcherResult {
+  matched: boolean;
+  unresolvable?: boolean;
+}
+
+function compilePattern(pattern: string): (candidate: string) => boolean {
+  return picomatch(pattern, { dot: false, nocase: false, nonegate: true });
+}
+
+function resolveEntityIds(pattern: string, catalog: CatalogSnapshot): Set<EntityId> {
+  const ids = new Set<EntityId>();
+  const isMatch = compilePattern(pattern);
+  for (const entity of catalog.entities) {
+    const refs = [entity.id, ...(entity.refs ?? [])];
+    if (refs.some((ref) => isMatch(ref))) {
+      ids.add(entity.id);
+    }
+  }
+  return ids;
+}
+
+function entitiesForPaths(changedFiles: readonly string[], catalog: CatalogSnapshot): Set<EntityId> {
+  const ids = new Set<EntityId>();
+  for (const entity of catalog.entities) {
+    for (const entityPath of entity.paths ?? []) {
+      const isMatch = compilePattern(entityPath);
+      if (changedFiles.some((path) => isMatch(path))) {
+        ids.add(entity.id);
+        break;
+      }
+    }
+  }
+  return ids;
+}
+
+export function matchEntityPattern(
+  pattern: string,
+  changedFiles: readonly string[],
+  catalog: CatalogSnapshot | undefined,
+): EntityMatcherResult {
+  if (!catalog) {
+    return { matched: false, unresolvable: true };
+  }
+
+  const entityIds = resolveEntityIds(pattern, catalog);
+  if (entityIds.size === 0) {
+    return { matched: false };
+  }
+
+  const changedEntityIds = entitiesForPaths(changedFiles, catalog);
+  return {
+    matched: [...entityIds].some((id) => changedEntityIds.has(id)),
+  };
+}
+
+export function isAlwaysInertType(type: string): type is Exclude<InertMatcherType, 'entity'> {
+  return type === 'resource' || type === 'api' || type === 'data';
+}

package/src/affects/matchers/package.ts

@@ -0,0 +1,102 @@
+import semver from 'semver';
+
+export interface ChangedDependency {
+  name: string;
+  version: string;
+}
+
+export interface ParsedPackagePattern {
+  name: string;
+  range?: string;
+}
+
+export interface PackageMatcherResult {
+  matched: boolean;
+  unresolvable?: boolean;
+  badPattern?: boolean;
+}
+
+export function parsePackagePattern(pattern: string): ParsedPackagePattern | undefined {
+  const splitAt = pattern.lastIndexOf('@');
+  const hasRange = splitAt > 0;
+  const name = hasRange ? pattern.slice(0, splitAt) : pattern;
+  const range = hasRange ? pattern.slice(splitAt + 1).trim() : undefined;
+
+  if (!name.trim() || (hasRange && !range)) {
+    return undefined;
+  }
+
+  if (range && !semver.validRange(range)) {
+    return undefined;
+  }
+
+  return range ? { name, range } : { name };
+}
+
+export function matchPackagePattern(
+  pattern: string,
+  changedDependencies: readonly ChangedDependency[] | undefined,
+): PackageMatcherResult {
+  const parsed = parsePackagePattern(pattern);
+  if (!parsed) {
+    return { matched: false, badPattern: true };
+  }
+
+  if (!changedDependencies) {
+    return { matched: false, unresolvable: true };
+  }
+
+  return {
+    matched: changedDependencies.some(
+      (dependency) =>
+        dependency.name === parsed.name &&
+        (!parsed.range || semver.satisfies(dependency.version, parsed.range)),
+    ),
+  };
+}
+
+function parseBunLockPackageLine(line: string): ChangedDependency | undefined {
+  const match = line.match(/^\s*"([^"]+)":\s*\["([^"]+)"/);
+  if (!match) return undefined;
+
+  const [, name, descriptor] = match;
+  if (!name || !descriptor?.startsWith(`${name}@`)) return undefined;
+
+  const version = descriptor.slice(name.length + 1);
+  if (!semver.valid(version)) return undefined;
+
+  return { name, version };
+}
+
+/**
+ * Derives the v1 package snapshot from a unified diff of `bun.lock`.
+ * Only Bun's text lockfile package entries are supported.
+ */
+export function deriveChangedDependenciesFromBunLockDiff(diff: string): ChangedDependency[] {
+  const added = new Map<string, Set<string>>();
+  const removed = new Map<string, Set<string>>();
+
+  for (const line of diff.split(/\r?\n/)) {
+    if (line.startsWith('+++') || line.startsWith('---')) continue;
+    const bucket = line.startsWith('+') ? added : line.startsWith('-') ? removed : undefined;
+    if (!bucket) continue;
+
+    const dependency = parseBunLockPackageLine(line.slice(1));
+    if (!dependency) continue;
+
+    let versions = bucket.get(dependency.name);
+    if (!versions) {
+      versions = new Set<string>();
+      bucket.set(dependency.name, versions);
+    }
+    versions.add(dependency.version);
+  }
+
+  const changedNames = new Set([...added.keys(), ...removed.keys()]);
+  return [...changedNames]
+    .flatMap((name) => {
+      const versions = new Set([...(added.get(name) ?? []), ...(removed.get(name) ?? [])]);
+      return [...versions].map((version) => ({ name, version }));
+    })
+    .sort((a, b) => a.name.localeCompare(b.name) || a.version.localeCompare(b.version));
+}

package/src/affects/matchers/path.ts

@@ -0,0 +1,37 @@
+import picomatch from 'picomatch';
+
+export interface PathMatcherResult {
+  matched: boolean;
+  badPattern?: 'leading-slash' | 'invalid-glob';
+}
+
+function normalizeCandidate(path: string): string {
+  return path.replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+function hasDotSegment(path: string): boolean {
+  return path.split('/').some((segment) => segment.startsWith('.') && segment !== '.' && segment !== '..');
+}
+
+function patternAllowsDotSegment(pattern: string): boolean {
+  return pattern.split('/').some((segment) => segment.startsWith('.') && segment !== '.' && segment !== '..');
+}
+
+export function matchPathPattern(pattern: string, changedFiles: readonly string[]): PathMatcherResult {
+  if (pattern.startsWith('/')) {
+    return { matched: false, badPattern: 'leading-slash' };
+  }
+
+  try {
+    const isMatch = picomatch(pattern, { dot: false, nocase: false, nonegate: true });
+    const allowsDot = patternAllowsDotSegment(pattern);
+    return {
+      matched: changedFiles.some((path) => {
+        const candidate = normalizeCandidate(path);
+        return (!hasDotSegment(candidate) || allowsDot) && isMatch(candidate);
+      }),
+    };
+  } catch {
+    return { matched: false, badPattern: 'invalid-glob' };
+  }
+}

package/src/check/index.ts

@@ -0,0 +1,121 @@
+import type { Adr } from '../schema/adr.schema.ts';
+import { resolveAffects, type FiredMatcher, type ResolutionSnapshots } from '../affects/index.ts';
+import { sortFindings, type Finding } from '../validate/findings.ts';
+
+/**
+ * The full result of `lintCorpus` — records, findings, and the checked count.
+ * `checkChanges` takes the whole result (not just `records`) because `lintCorpus`
+ * drops malformed files from `records` while keeping their `error` findings; those
+ * errors must still count toward `ok` when the malformed file was changed (RC3/R1).
+ */
+export interface CheckLintResult {
+  records: Adr[];
+  findings: Finding[];
+  checked: number;
+}
+
+export interface GoverningDecision {
+  recordId: string;
+  title: string;
+  firedMatchers: FiredMatcher[];
+}
+
+/**
+ * The stable structure `adr check --json` emits and the `@adrkit/ci` Action consumes.
+ * Deterministic and pure: identical `(lint, changedFiles, snapshots)` → identical output.
+ */
+export interface CheckOutcome {
+  changedFiles: string[];
+  governedBy: GoverningDecision[];
+  changedRecords: string[];
+  findings: Finding[];
+  ok: boolean;
+}
+
+export interface CheckChangesInput {
+  lint: CheckLintResult;
+  changedFiles: readonly string[];
+  /** Corpus directory (default `docs/adr`) used to identify changed records. */
+  dir?: string;
+  snapshots?: ResolutionSnapshots;
+  /** Optional current-repo identity for scoped (`repo`-qualified) matchers. */
+  log?: string;
+}
+
+const RECORD_BASENAME = /^\d{4,}-.+\.md$/;
+const TEMPLATE_BASENAME = '0000-template.md';
+
+function normalizeDir(dir: string | undefined): string {
+  const forward = (dir ?? 'docs/adr').replace(/\\/g, '/');
+  // Strip trailing slashes without a regex (avoids super-linear scanning on
+  // pathological input — the changed-file paths are attacker-controlled).
+  let end = forward.length;
+  while (end > 0 && forward.charCodeAt(end - 1) === 47 /* '/' */) end -= 1;
+  const stripped = forward.slice(0, end);
+  // A root corpus ("." or now-empty) is the repo root — no path prefix, so
+  // repo-relative changed files (which never start with "./") still match.
+  return stripped === '.' ? '' : stripped;
+}
+
+function toForwardSlash(path: string): string {
+  return path.replace(/\\/g, '/');
+}
+
+/**
+ * Whether a repo-relative changed file is an ADR record under `dir`, using the same
+ * flat-directory + filename grammar the corpus loader enforces. Pure string logic —
+ * no filesystem access — so a malformed record dropped from `lint.records` is still
+ * recognized as a changed record and its `error` findings count toward `ok`.
+ */
+function isCorpusRecordPath(file: string, dir: string): boolean {
+  // An empty dir (root corpus) yields an empty prefix, not "/".
+  const prefix = dir ? `${dir}/` : '';
+  if (!file.startsWith(prefix)) return false;
+  const rest = file.slice(prefix.length);
+  if (rest.length === 0 || rest.includes('/')) return false;
+  return rest !== TEMPLATE_BASENAME && RECORD_BASENAME.test(rest);
+}
+
+function uniqueSorted(values: readonly string[]): string[] {
+  return [...new Set(values)].sort((a, b) => a.localeCompare(b));
+}
+
+/**
+ * The single, neutral "resolve governing decisions + validate changed records"
+ * implementation, called by both `adr check` (CLI) and the `@adrkit/ci` Action so
+ * neither surface depends on the other. Pure: no clock, network, or fs traversal
+ * beyond the already-loaded lint result (ADR-0009).
+ */
+export function checkChanges(input: CheckChangesInput): CheckOutcome {
+  const dir = normalizeDir(input.dir);
+  const changedFiles = uniqueSorted(input.changedFiles.map(toForwardSlash));
+  const changedRecords = changedFiles.filter((file) => isCorpusRecordPath(file, dir));
+  const changedRecordSet = new Set(changedRecords);
+
+  const resolution = resolveAffects({
+    records: input.lint.records,
+    changedFiles,
+    snapshots: input.snapshots,
+    log: input.log,
+  });
+
+  const titleById = new Map(
+    input.lint.records.map((record) => [record.frontmatter.id, record.frontmatter.title]),
+  );
+  const governedBy: GoverningDecision[] = resolution.matches.map((match) => ({
+    recordId: match.recordId,
+    title: titleById.get(match.recordId) ?? '',
+    firedMatchers: match.firedMatchers,
+  }));
+
+  // Findings kept only for files lint attributes to a changed record. Errors on
+  // unchanged records (A5) and corpus-level findings without a record path do not
+  // fail the check.
+  const changedRecordFindings = input.lint.findings.filter(
+    (finding) => finding.path !== undefined && changedRecordSet.has(finding.path),
+  );
+  const findings = sortFindings([...resolution.findings, ...changedRecordFindings]);
+  const ok = !changedRecordFindings.some((finding) => finding.severity === 'error');
+
+  return { changedFiles, governedBy, changedRecords, findings, ok };
+}

package/src/graph/build.ts

@@ -0,0 +1,94 @@
+import type { Adr } from '../schema/adr.schema.ts';
+
+export interface GraphNode {
+  id: string;
+  title: string;
+  status: string;
+}
+
+export interface GraphEdge {
+  from: string;
+  to: string;
+  kind: 'supersedes' | 'relatesTo' | 'conflictsWith';
+}
+
+export interface AdrGraph {
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+}
+
+function edgeKey(edge: GraphEdge): string {
+  return `${edge.from}\u0000${edge.to}\u0000${edge.kind}`;
+}
+
+function pushEdge(edges: Map<string, GraphEdge>, ids: Set<string>, edge: GraphEdge): void {
+  if (!ids.has(edge.from) || !ids.has(edge.to)) return;
+  edges.set(edgeKey(edge), edge);
+}
+
+export function buildAdrGraph(records: readonly Adr[]): AdrGraph {
+  const sortedRecords = [...records].sort((a, b) => a.frontmatter.id.localeCompare(b.frontmatter.id));
+  const ids = new Set(sortedRecords.map((record) => record.frontmatter.id));
+  const edges = new Map<string, GraphEdge>();
+
+  for (const record of sortedRecords) {
+    for (const superseded of record.frontmatter.supersedes) {
+      pushEdge(edges, ids, { from: record.frontmatter.id, to: superseded, kind: 'supersedes' });
+    }
+
+    if (record.frontmatter.supersededBy) {
+      pushEdge(edges, ids, {
+        from: record.frontmatter.supersededBy,
+        to: record.frontmatter.id,
+        kind: 'supersedes',
+      });
+    }
+
+    for (const related of record.frontmatter.relatesTo) {
+      pushEdge(edges, ids, { from: record.frontmatter.id, to: related, kind: 'relatesTo' });
+    }
+
+    for (const conflict of record.frontmatter.conflictsWith) {
+      pushEdge(edges, ids, { from: record.frontmatter.id, to: conflict, kind: 'conflictsWith' });
+    }
+  }
+
+  return {
+    nodes: sortedRecords.map((record) => ({
+      id: record.frontmatter.id,
+      title: record.frontmatter.title,
+      status: record.frontmatter.status,
+    })),
+    edges: [...edges.values()].sort(
+      (a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to) || a.kind.localeCompare(b.kind),
+    ),
+  };
+}
+
+function dotString(value: string): string {
+  return `"${value
+    .replace(/\\/g, '\\\\')
+    .replace(/\r/g, '\\n')
+    .replace(/\n/g, '\\n')
+    .replace(/"/g, '\\"')}"`;
+}
+
+export function renderDotGraph(graph: AdrGraph): string {
+  const lines = ['digraph adr {', '  rankdir=LR;'];
+  for (const node of graph.nodes) {
+    lines.push(
+      `  ${dotString(node.id)} [label=${dotString(`${node.id}: ${node.title}`)}, status=${dotString(
+        node.status,
+      )}];`,
+    );
+  }
+  for (const edge of graph.edges) {
+    lines.push(`  ${dotString(edge.from)} -> ${dotString(edge.to)} [label=${dotString(edge.kind)}];`);
+  }
+  lines.push('}');
+  return `${lines.join('\n')}\n`;
+}
+
+export function renderJsonGraph(graph: AdrGraph): string {
+  return `${JSON.stringify(graph, null, 2)}\n`;
+}