Skip to content

fix(core): report repo-qualified affects matchers instead of skipping them silently (#300) - #308

Merged
mbeacom merged 2 commits into
mainfrom
fix/repo-qualified-matchers
Oct 10, 2026
Merged

mbeacom merged 2 commits into
mainfrom
fix/repo-qualified-matchers

Conversation

@mbeacom

@mbeacom mbeacom commented Oct 10, 2026

Copy link
Copy Markdown
Owner

Closes #300.

What and why

A repo-qualified affects matcher in a single-repository corpus can't apply, and it used to vanish without a finding. That's the worst kind of failure under ADR-0016. The comparison read a log input that no caller ever set (the issue blamed Adr.log, but it was ResolveAffectsInput.log).

  • adr check and adr explain report each skipped matcher as affects-repo-not-applicable (info), and adr lint reports one per record, so a corpus-wide run surfaces it without needing a path. On this repo, ADR-0056's four resource matchers for mbeacom/adrkit-azure now print one info line in adr lint.
  • info, no exit-code authority. ADR-0059 clause 11 names it that way, it matches affects-unresolvable, and exit codes read only error. --json output grows additively.
  • Federation hook, prepared but not wired. matcherAppliesToMember(matcher, { log, repo } | undefined) replaces matcherAppliesToLog, and ResolveAffectsInput.log / CheckChangesInput.log become member?. That's a type-level change for a TypeScript caller of @adrkit/core that passed log. None did, so runtime behavior is unchanged, and the CHANGELOG says so.

Checklist

  • DCO signed off.
  • Recorded decision: ADR-0059 clause 11 (accepted), ADR-0016, and ADR-0022.
  • Schema changed: n/a. I deliberately didn't edit adr.schema.ts, which is pinned.
  • @adrkit/core changed, so packages/ci/dist is regenerated under linux/amd64 Bun 1.4.2. The non-reorder diff is only this change.
  • Observed failing first (ADR-0016):
    • core: 9 of 12 failed against stubs (the 3 that passed guard unchanged behavior);
    • CLI: all 4 failed with core stashed;
    • mutations: always emitting, and changing the severity to warn.
  • Full bun test: 4349 pass. typecheck, lint, check:deps, check:stale-refs, check:changelog, and adr lint (59 records, 0 errors, 0 warnings, 1 info) pass.

Notes for reviewers

Copilot AI balanced review requested due to automatic review settings October 10, 2026 21:43
@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown

Decisions governing this change

11 accepted decisions govern this change

Show all 11 governing decisions and why each applies
  • 0003 — Ship as a Spec Kit extension plus a standalone CLI, not a competing harness
    • via path: packages/cli/**
  • 0009 — Pin affects resolution semantics and bind entity refs to pluggable catalogs
    • via path: packages/core/src/affects/**
  • 0013 — Reconcile adapter isolation and catalog binding with the offline snapshot generator
    • via path: packages/core/src/affects/**
  • 0016 — Require every check to be observed failing before it counts as coverage
    • via path: packages/*/test/**
    • via path: packages/core/src/validate/**
  • 0022 — Scan inbound markers in check and CI without giving them exit-code authority
  • 0029 — Scope Backstage publication as a downstream consumer, tiered on the entity-ownership mapping
    • via path: packages/catalog-envelope/**
    • via path: packages/core/src/affects/**
    • via path: packages/core/src/check/**
    • via path: packages/core/src/index.ts
  • 0030 — Keep extension surfaces that carry a dependency tree outside this repository
    • via path: packages/ci/**
  • 0031 — Publish a narrow consumer SDK as the contract, and document the CLI JSON as its sibling
    • via path: packages/core/src/index.ts
  • 0035 — Execute the gates that certify a pull request from the default branch
    • via path: packages/ci/**
  • 0036 — Expose the governing-decisions Action through one root Marketplace entry point
    • via path: packages/ci/dist/index.js
  • 0041 — Regenerate committed artifacts on Dependabot pull requests with default-branch scripts behind a maintainer label
    • via path: packages/ci/dist/**

Links point at 770a0f0, this run's GITHUB_SHA. Run adr explain <path> locally to see why a file is governed.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Member-aware checks can still emit the contradictory single-repository advisory when the qualified ADR itself changes.

1 open finding
What changed in this PR

Adds informational findings for repo-qualified affects matchers that cannot apply in single-repository runs.

Changes:

  • Adds member-aware matcher resolution and lint advisories.
  • Adds core/CLI coverage and updates public exports.
  • Regenerates committed CI bundles and documents the change.

Decision-context MCP was unavailable, so ADR compliance was not independently verified.

File Description
CHANGELOG.md Documents the behavior and API change.
packages/​catalog-envelope/​test/​no-core-schema-change.test.ts Explains the protected-surface update.
packages/​catalog-envelope/​test/​protected-surfaces.json Updates the affects resolver digest.
packages/​ci/​dist/​index.js Regenerates the governing-decisions bundle.
packages/​ci/​dist/​portal-action.js Regenerates the portal Action bundle.
packages/​ci/​dist/​queue-action.js Regenerates the queue Action bundle.
packages/​cli/​test/​lint.test.ts Allows informational lint output.
packages/​cli/​test/​repo-qualified-matchers.test.ts Tests CLI advisory behavior.
packages/​core/​src/​affects/​index.ts Adds member-aware matching and findings.
packages/​core/​src/​check/​index.ts Passes member identity into resolution.
packages/​core/​src/​index.ts Exports the new validator.
packages/​core/​src/​validate/​affects-repo-qualifier.ts Adds corpus-wide qualifier validation.
packages/​core/​src/​validate/​index.ts Runs the new lint validation.
packages/​core/​test/​affects-repo.test.ts Tests resolution, lint, and federation behavior.
packages/​core/​test/​surface.test.ts Updates public runtime export expectations.

🧠 Review effort: Balanced

Comment thread packages/core/src/check/index.ts
@mbeacom mbeacom self-assigned this Oct 10, 2026
@mbeacom mbeacom added bug Something isn't working gate-change-acknowledged A maintainer has seen and accepted this PR's change to the CI gate surface (ADR-0035) labels Oct 10, 2026
… them silently (#300)

A matcher such as `{ type: path, pattern: "src/**", repo: "payments" }`
names another repository, so in a single-repository corpus it never
matches, and until now it was also skipped with no finding: the compare
read an input `log` that no caller set. `adr check` and `adr explain` now
report each skipped matcher as `affects-repo-not-applicable` (info), and
`adr lint` reports one per record, so ADR-0056's matchers for
mbeacom/adrkit-azure surface on a corpus-wide run. The finding is info, as
ADR-0059 clause 11 names it, and changes no exit code.

In @adrkit/core the unused `log` input on resolveAffects and checkChanges
is replaced by an explicit `member: { log, repo }`, and
matcherAppliesToMember applies a qualified matcher when it equals either
name (ADR-0059 clause 11, prepared, not wired). packages/ci/dist is
rebuilt under linux/amd64 Bun 1.4.2. Every new test was observed failing
first (ADR-0016).

Signed-off-by: Mark Beacom <m@beacom.dev>
Copilot found that checkChanges with a member suppressed the resolver's affects-repo-not-applicable but re-added lint's copy through the changed-record findings when the qualified ADR itself changed, so a federated check could apply a matcher and also say it cannot apply. With a member, the resolver has already decided every qualified matcher (applied, or silent because it names another member), so lint's single-repository advisory is dropped there. Integration test runs lintCorpus then checkChanges with the qualified record as a changed file; the two member cases failed before the fix (ADR-0016). packages/ci/dist/index.js rebuilt under linux/amd64 Bun 1.4.2 (one line).

Signed-off-by: Mark Beacom <m@beacom.dev>
@mbeacom
mbeacom force-pushed the fix/repo-qualified-matchers branch from bec9587 to 0ffac1d Compare October 10, 2026 23:29
@github-actions github-actions Bot removed the gate-change-acknowledged A maintainer has seen and accepted this PR's change to the CI gate surface (ADR-0035) label Oct 10, 2026
@mbeacom mbeacom added the gate-change-acknowledged A maintainer has seen and accepted this PR's change to the CI gate surface (ADR-0035) label Oct 10, 2026
@mbeacom
mbeacom enabled auto-merge (squash) October 10, 2026 23:31
@mbeacom
mbeacom merged commit 2d81f2b into main Oct 10, 2026
23 of 24 checks passed
@mbeacom
mbeacom deleted the fix/repo-qualified-matchers branch October 10, 2026 23:33
mbeacom added a commit that referenced this pull request Oct 10, 2026
…est the portal bundle's datetime as-of

packages/ci/dist rebuilt under linux/amd64 Bun 1.4.2 on top of main (after #307, #308, #314). The portal bundle now takes the SDK's --as-of grammar: a new bundle test resolves 2026-01-08T23:30:00-05:00 to 2026-01-09, and the usage-error test uses a timezone-less datetime with core's message. Both failed against main's bundle (ADR-0016).

Signed-off-by: Mark Beacom <m@beacom.dev>
mbeacom added a commit that referenced this pull request Oct 10, 2026
…ut publishing it (#295) (#312)

* feat(core,cli,sdk): close the SDK's remaining publication gates without publishing it (#295)

- ADR-0031 item 8 / ADR-0053 item 3: core exports todayUtcDate, the
  absent-input `--as-of` default, and replaces every inline copy: adr
  queue, the queue Action (bundle regenerated), adr new's scaffold, and
  the SDK's queue(). The portal now takes the SDK's echoed default
  (queue().asOf) instead of computing its own. Tests ban the inline
  expression in all of them.
- ADR-0031 item 4 / ADR-0053 item 8: `adr explain`, `adr lint`, and
  `adr new --json` now come from core formatters (packages/core/src/
  report). Old and new CLIs produced byte-identical stdout and exit codes
  on 53 command lines over this corpus and the SDK fixtures; committed
  goldens hold it.
- ADR-0031 item 6 / ADR-0053 item 5: a conformance fixture under
  packages/core/test/conformance/golden: the CLI must reproduce its
  queue and check goldens byte for byte, and the SDK must agree with them.
- ADR-0031 item 5: docs/RELEASING.md documents the SDK and CLI JSON
  consumer contracts.

Nothing is published: RELEASE_PACKAGES, exports, files, and the
no-release assertions are untouched. packages/ci/dist rebuilt under
linux/amd64 Bun 1.4.2. Every new test was observed failing first
(ADR-0016). Ticked: ADR-0031 items 4, 5, 6, 8 and ADR-0053 items 3, 5, 8.

Signed-off-by: Mark Beacom <m@beacom.dev>

* fix(sdk,portal): accept the CLI's --as-of grammar in queue(), so the portal takes ISO datetimes

Review on #312 found three gaps:
- #295 promised the portal would accept ISO datetimes once the default
  moved to core, but it still refused them. The SDK's queue({ asOf }) now
  resolves a supplied value through core's resolveAsOf, the grammar
  `adr queue --as-of` uses (a bare date, or an ISO datetime with an
  explicit zone), and echoes the resolved UTC date in QueueView.asOf;
  anything else throws RangeError. The portal passes the caller's asOf
  to queue() and builds from view.asOf, so it accepts datetimes while
  importing only the SDK. No new SDK symbol; the doc no longer tells
  callers to reach into core.
- The portal's default-date test could fail across UTC midnight; it now
  brackets both readings and compares only when no midnight passed.
- docs/sdk-surface.md and the ADR-0031 item 8 note still described the
  portal's removed copy and bare-date rule.

New tests were observed failing first (ADR-0016), including SDK/CLI
equivalence for a datetime asOf on all four corpora.

Signed-off-by: Mark Beacom <m@beacom.dev>

* build(ci): rebuild the Action bundles after rebasing onto main, and test the portal bundle's datetime as-of

packages/ci/dist rebuilt under linux/amd64 Bun 1.4.2 on top of main (after #307, #308, #314). The portal bundle now takes the SDK's --as-of grammar: a new bundle test resolves 2026-01-08T23:30:00-05:00 to 2026-01-09, and the usage-error test uses a timezone-less datetime with core's message. Both failed against main's bundle (ADR-0016).

Signed-off-by: Mark Beacom <m@beacom.dev>

---------

Signed-off-by: Mark Beacom <m@beacom.dev>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working gate-change-acknowledged A maintainer has seen and accepted this PR's change to the CI gate surface (ADR-0035)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

core: repo-qualified affects matchers are skipped silently, because Adr.log is never set

2 participants