Skip to content

fix(reference): reconcile excluded symlink identities - #2907

Closed
Adkid-Zephyr wants to merge 11 commits into
morluto:mainfrom
Adkid-Zephyr:fix/reference-excluded-symlink
Closed

Adkid-Zephyr wants to merge 11 commits into
morluto:mainfrom
Adkid-Zephyr:fix/reference-excluded-symlink

Conversation

@Adkid-Zephyr

@Adkid-Zephyr Adkid-Zephyr commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Fixes #2651. Thanks to @coygeek for the original report.

Validate excluded symlink targets without conflating distinct filesystem spellings or repeatedly walking and normalizing long path prefixes. Current main supplies the exclusion-kind metadata and missing-target handling; this PR preserves those behaviors and completes graph consistency and identity checks.

Problem and expected behavior

A source tree may contain an excluded directory café and a different file cafe\u0301. Their recorded filesystem identities must not be conflated when checking entry kinds. Symbolic-reference lookup can still use an unambiguous Unicode fallback.

An internal target must also agree with the recorded facts: an escape is not an omission, an excluded file cannot establish subtree coverage, and directory evidence cannot contradict an inventoried file at the same exact path. Unknown kind remains unknown.

Change and scope

  • Compare exclusion/inventory kinds by exact recorded spelling.
  • Match recorded prefixes through lazy exact/canonical component indexes. Normalize each query once and retain unknown identity when a prefix is ambiguous.
  • Validate every applicable excluded prefix: only directory evidence covers descendants; exact omissions keep their existing meaning. Escape facts never supply internal-target coverage.
  • Skip exclusion lookup for already-inventoried targets. Remove the superseded parent-walking API and preserve upstream missing-target, literal-path, and exclusion-kind behavior.

Contract and boundary impact

  • Semantic owners: historical-source graph validation and reference-path identity.
  • Contribution scope: ordinary static source-import correctness; no new provider or capability requiring a separate scope decision.
  • CLI/MCP: the current-main graph shape and exclusion-kind schema remain unchanged. New checks reject contradictory graph facts while preserving valid imported source metadata and partial inventories.
  • Evidence: exact source spellings, exclusion reasons/patterns, hashes, and unknowns remain preserved. Existing graph commitments are not rewritten.
  • Platform coverage: macOS source/CLI tests; Linux filename-coexistence fixture is included for CI. No real analysis engine or paid API is involved.

Expected operation effects:

  • Read existing files or captured data.
  • Launch or attach to a process.
  • Inject instrumentation or run scripts/code.
  • Change process memory, registers, files, or configuration.
  • Contact network services.
  • Recover protected code or work around protections.
  • Documentation or usability only; no target interaction.
  • Not sure yet; investigation or maintainer guidance needed.

Evidence and regression coverage

The original source-import failure and later review findings were reproduced before their corrections. Coverage includes distinct NFC/NFD filesystem names, exact kind conflicts, unknown kind, legacy omissions, directory descendants, escapes, mixed exclusion kinds, sibling boundaries, and source preservation.

A small 128-component query made 128 normalization calls with the original parent walker and one with the component index. This is a resource-work regression, not an end-to-end latency, token, CPU, or memory improvement claim.

  • Observed, derived, and inferred claims remain distinguishable.
  • Artifact identity, source provenance, and failed attempts remain preserved.
  • Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.

Validation performed

Pinned Node 24.18.0 / npm 11.16.0; head 1092f12d includes main 500e3239 and preserves maintainer commits:

  • All 26 reference-source suites through npm run test:focused — 139 passed, 3 skipped. One skip is the new Linux filesystem-coexistence test; its platform-independent graph regression passed locally.
  • npm run check — passed, including architecture guards.
  • npm run docs:check — passed, including 5 consistency tests.
  • npm run verify:test-discovery — 1,244 files discovered exactly once.
  • git diff --check — passed.

The eight suites implicated in the preceding CI run were also rerun after incorporating upstream #3080 and the README-fact isolation fix: 117 passed (injected IDA protocol fixture, no real provider). The full suite and actual Linux coexistence case remain for current-head CI. Local test results do not claim CI or maintainer approval.

Compatibility, safety, and release

No new graph field relative to current main, provider, package entrypoint, or installation behavior. Static import remains read-only. Tests use self-created fixtures. Main's general exclusion-kind and missing-target behavior is retained rather than replaced by the earlier narrower representation.

Implementation, regression tests, conflict resolution, and self-review were assisted by OpenAI Codex.

Before merge

  • This PR addresses a concrete problem or an agreed enhancement.
  • Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff.
  • The PR has one focused outcome and the title follows type(scope): outcome.
  • Related issue is linked, or the reason for not linking one is stated above.
  • Tests cover changed observable behavior and meaningful failure paths.
  • Owning docs, contracts, and generated metadata are updated where needed.
  • User-visible CLI/MCP changes include representative output coverage.
  • I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 13, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-13T23:12:31.222257Z 3cd5f6c New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@greptile-apps

greptile-apps Bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerConfidence Score: 5/5

[Medium impact] The PR appears safe to merge; no actionable defects were found.

Summary

The PR separates exact filesystem spellings from Unicode fallback and replaces repeated parent lookups with lazy component indexes.

  • Internal symlinks need matching inventory or exclusion evidence.
  • Path lookups find recorded prefixes without repeatedly walking parents.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Internal symlink target] --> B{Target is inventoried?}
  B -->|Yes| C[Keep existing target checks]
  B -->|No| D[Find recorded prefixes]
  D --> E{Prefixes are unambiguous?}
  E -->|No| F[Reject target]
  E -->|Yes| G{Every prefix permits coverage?}
  G -->|No| F
  G -->|Yes| H[Accept excluded target]
Loading

Reviews (10) · Last reviewed commit: "Merge remote-tracking branch 'origin/mai..." · Reviewed by Greptile

@chatgpt-codex-connector chatgpt-codex-connector Bot 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.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5eb1a004b9

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/domain/referenceSourceGraph.ts Resolved
Comment thread src/domain/referenceSourceGraph.ts Resolved
@morluto
morluto force-pushed the fix/reference-excluded-symlink branch from acba6fa to afcbce4 Compare October 13, 2026 18:08

@chatgpt-codex-connector chatgpt-codex-connector Bot 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.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: afcbce4925

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/domain/referenceSourceGraph.ts Resolved
@morluto
morluto force-pushed the fix/reference-excluded-symlink branch from afcbce4 to ddcf37d Compare October 13, 2026 18:24
@morluto
morluto force-pushed the fix/reference-excluded-symlink branch from ddcf37d to 1786fdd Compare October 13, 2026 18:37

@chatgpt-codex-connector chatgpt-codex-connector Bot 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.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1786fdd001

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@chatgpt-codex-connector chatgpt-codex-connector Bot 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.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b1f097bcc2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/domain/referenceSourceGraph.ts Resolved

@chatgpt-codex-connector chatgpt-codex-connector Bot 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.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3cd5f6c279

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/domain/referenceSourceGraph.ts Resolved
@morluto morluto added area: domain Domain logic, errors, and pure functions bug Something isn't working labels Oct 14, 2026
@chatgpt-codex-connector

Copy link
Copy Markdown

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Repo admins can enable using credits for code reviews in their settings.

Comment thread src/domain/referenceSourceGraph.ts Resolved
…d-symlink

# Conflicts:
#	docs/cli.md
#	src/application/ReferenceSourceImport.ts
#	src/domain/referenceSourceGraph.test.ts
#	src/domain/referenceSourceGraph.ts
#	src/domain/referenceSourcePathIdentity.ts
#	tests/boundary/cli/referenceSourceExclusions.test.ts
#	tests/boundary/filesystem/referenceSourceImport.test.ts
@chatgpt-codex-connector

Copy link
Copy Markdown

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Repo admins can enable using credits for code reviews in their settings.

@Adkid-Zephyr Adkid-Zephyr changed the title fix(reference): retain links to excluded source paths fix(reference): reconcile excluded symlink identities Oct 14, 2026
@chatgpt-codex-connector

Copy link
Copy Markdown

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Repo admins can enable using credits for code reviews in their settings.

@Adkid-Zephyr

Copy link
Copy Markdown
Contributor Author

All reported review findings have been addressed on 1092f12df19d1dfeec50a30245a56829ffdbf988, preserving the maintainer changes and current-main exclusion semantics. Required CI is now successful, including source tests and all five built test shards: https://github.com/morluto/rea/actions/runs/38515278504. All review threads are resolved, and Greptile reports no actionable defects on this head. The latest Codex review could not run because of the repository review quota, so I am not claiming a fresh Codex approval.

The final diff covers exact filesystem-kind consistency, exclusion applicability, and bounded component-prefix lookup. Local verification is recorded in the PR description. This is ready for your final maintainer review and merge when convenient. Thank you for the fixes and guidance along the way.

@morluto

morluto commented Oct 15, 2026

Copy link
Copy Markdown
Owner

Superseded by the delivered change on main: ec271121e. Reference-source exclusion handling verifies symlink target identity and applicability instead of treating unrelated path spellings as an exclusion match. Closing this earlier proposal. Current main qualification passed: https://github.com/morluto/rea/actions/runs/38690953281.

@morluto morluto closed this Oct 15, 2026
@morluto

morluto commented Oct 15, 2026

Copy link
Copy Markdown
Owner

Thanks @Adkid-Zephyr for checking how excluded symlinks retain their identity. Main includes the identity-preserving path handling.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: domain Domain logic, errors, and pure functions bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

fix(reference-source): default directory exclusion makes a retained symlink abort import

2 participants