fix: unified base path resolution semantics

[osterman]

What

Establishes a unified convention for base path resolution where the meaning of a value is determined by its form and the context is determined by its source:

• Empty ("") → smart defaults (git root search)
• Dot (".", "./foo", "..", "../foo") → explicit anchor to "here" (context-dependent: config dir in atmos.yaml, CWD in env vars/CLI/provider)
• Bare ("foo", "stacks") → search path (git root search, source-independent)
• Absolute ("/path") → pass through unchanged

This eliminates source-dependent behavior for bare paths: ATMOS_BASE_PATH=stacks now goes through the same git root search as base_path: stacks in atmos.yaml.

Why

The previous PRD had inverted semantics for runtime sources (FR6), causing confusion about whether env vars should be CWD-relative or config-relative. The new convention is logically consistent:

• Empty is absence of opinion
• Dot is a signal ("here") that adapts to context (just like . works in every shell tool)
• Bare paths are names to search, not location-relative references

This fixes issues #2183 and #1858 while preserving the "run from anywhere" behavior that users expect.

Testing

• 8 new test functions covering source-aware resolution
• All existing tests pass
• config package tests: 100% passing

References

Stacked on #2215 (aknysh/fix-import-not-found).
Fixes #2183 (Spacelift scenario).
Fixes #1858 (ATMOS_CLI_CONFIG_PATH with empty base_path).

Summary by CodeRabbit

• Bug Fixes

  • Fixed import resolution errors caused by base path configuration and Git root discovery
  • Enhanced error messages with additional context and guidance for path resolution failures

• New Features

  • Improved base path resolution to correctly distinguish between runtime-provided and configuration-file-sourced paths
  • Better handling of relative and absolute paths with appropriate resolution logic per source type

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues found.

Scanned Files

None

[coderabbitai]

Caution

Review failed

Failed to post review comments

📝 Walkthrough

Walkthrough

This PR addresses "failed to find import" errors by implementing source-aware base path resolution. It introduces a BasePathSource field to track whether base paths originate from runtime sources (env vars/CLI) or config files, adds dot-prefix resolution anchored to source-appropriate directories, enhances error messaging for glob matching failures, and provides comprehensive documentation and test coverage for the new semantics.

Changes

Cohort / File(s)	Summary
Documentation docs/fixes/2026-03-17-failed-to-find-import-base-path-resolution.md, docs/prd/base-path-resolution-semantics.md	Introduces formal base path resolution semantics with category-driven classification (Empty, Dot, Bare, Absolute), source tracking, and resolution algorithm. Documents root cause of import failures and interim fixes.
Schema pkg/schema/schema.go	Added BasePathSource field to AtmosConfiguration struct to track whether base path originates from runtime sources or config file.
Core Path Resolution pkg/config/config.go	Enhanced resolveAbsolutePath with new source parameter to enable source-aware path resolution. Added resolveDotPrefixPath helper for dot-prefixed paths anchored to source-appropriate directories. Updated initialization to mark runtime-sourced base paths.
Error Handling pkg/config/utils.go, pkg/utils/glob_utils.go	Enriched error messages for glob matching failures with structured context and user-facing hints about base_path correctness and relative path handling.
Tests pkg/config/base_path_resolution_test.go, pkg/config/config_test.go	New comprehensive test file covering dot-slash, absolute, empty, and bare path resolution across sources. Updated existing tests to reflect runtime semantics for dot-prefixed paths resolved from shell context.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• #1773 — Both modify base_path resolution and git-root discovery behavior, affecting the same core path resolution logic.
• #1941 — Both introduce source-aware base path resolution semantics and modify git-root discovery behavior in configuration initialization.
• #2029 — Both address base path and component path resolution relative to AtmosBasePath and source-dependent anchoring.

Suggested labels

minor

Suggested reviewers

• aknysh

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix: unified base path resolution semantics' directly and concisely summarizes the main objective of the PR: establishing a unified convention for resolving base paths based on their form and source.
Linked Issues check	✅ Passed	Changes directly address both issues: #2183 (failed to find import in affected workflows) and #1858 (stack validation in CI pipelines) by implementing source-aware path resolution, ensuring bare paths use git-root search, and handling dot-prefixed paths differently for runtime vs config sources.
Out of Scope Changes check	✅ Passed	All changes align with the stated objectives: documentation updates formalize the resolution convention, test files cover new resolution scenarios, and code changes implement source-aware path resolution with enhanced error handling. No unrelated modifications detected.
Docstring Coverage	✅ Passed	Docstring coverage is 90.48% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch osterman/base-path-resolution

📝 Coding Plan

• Generate coding plan for human review comments

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

❌ Patch coverage is 80.00000% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 76.88%. Comparing base (c984616) to head (d75fe97).
⚠️ Report is 7 commits behind head on aknysh/fix-import-not-found.

Files with missing lines	Patch %	Lines
pkg/config/config.go	77.77%	2 Missing and 2 partials ⚠️

Additional details and impacted files

@@                       Coverage Diff                       @@
##           aknysh/fix-import-not-found    #2227      +/-   ##
===============================================================
- Coverage                        76.88%   76.88%   -0.01%     
===============================================================
  Files                             1001     1001              
  Lines                            95412    95411       -1     
===============================================================
- Hits                             73354    73353       -1     
+ Misses                           17789    17788       -1     
- Partials                          4269     4270       +1     

Flag	Coverage Δ
unittests	76.88% <80.00%> (-0.01%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
pkg/config/utils.go	88.05% <100.00%> (+0.03%)	⬆️
pkg/schema/schema.go	87.70% <ø> (ø)
pkg/config/config.go	69.41% <77.77%> (-1.14%)	⬇️

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.