FAQ and troubleshooting

Platform spec article

FAQ and troubleshooting

Back to Corelib discovery and packaging ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (4)

1. 0001-canonical-corelib-identity Canonical corelib package identity Accepted

   Published and resolved identity is corelib, not ad-hoc forks.

   Context

   Registry, CLI, and analysis must agree on one package name.

   Decision

   Rule	Detail
   Identity	Package name corelib; sources under beskid_corelib
   Legacy	standard_library paths may alias; identity remains corelib

   Consequences

   pckg publish, resolver, and docs use the same identity string.

   Verification anchors

   resolver.rs; beskid_tests corelib project fixtures.

   Open full ADR page

2. 0002-multi-path-discovery Multi-path corelib discovery Accepted

   Env, repo walk, and bundled CLI materialize the same tree.

   Context

   Developers run from superrepo, installed CLI, or CI without divergent roots.

   Decision

   Rule	Detail
   BESKID_CORELIB_ROOT	Points at root containing beskid_corelib/Project.proj
   Walk	Ancestor search for compiler/corelib/beskid_corelib
   Bundle	beskid_cli ensure_corelib_ready materializes embedded tree

   Consequences

   Missing roots fail fast with resolver diagnostics.

   Verification anchors

   corelib_runtime.rs; resolver.rs tests.

   Open full ADR page

3. 0003-readme-packaging-for-pckg Readme packaging for pckg artifacts Accepted

   Pack copies declared readme into README.md for registry docs.

   Context

   Registry consumers expect root README.md in .bpk artifacts.

   Decision

   Rule	Detail
   Declare	Optional readme = "path.md" in Project.proj
   Default	readme.md at package root when present
   Pack	beskid pckg pack places resolved file as README.md

   Consequences

   pckg documentation ingest uses consistent entry filename.

   Verification anchors

   PackagePublishDocumentation.cs; pack integration tests.

   Open full ADR page

4. 0004-workspace-includes-console-shard Workspace includes console shard Accepted

   corelib_console is a workspace member depended on by beskid_corelib.

   Context

   Console/ANSI must ship with the aggregate package, not as an orphan.

   Decision

   Rule	Detail
   Workspace	compiler/corelib/Workspace.proj lists packages/console
   Aggregate	beskid_corelib depends on corelib_console

   Consequences

   Publish CI packs the full workspace graph for registry corelib.

   Verification anchors

   Workspace.proj; corelib CI publish job.

   Open full ADR page

Articles

• Contracts and edge cases Normative guarantees and known edge cases for `Corelib discovery and packaging`. article Standard
• Design model Conceptual model for `Corelib discovery and packaging` and its subsystem boundaries. article Standard
• Examples Practical examples that demonstrate `Corelib discovery and packaging` behavior. article Standard
• FAQ and troubleshooting Common questions and debugging guidance for `Corelib discovery and packaging`. article Standard
• Flow and algorithm End-to-end control flow for corelib discovery, materialization, and packaging. article Standard
• Verification and traceability How `Corelib discovery and packaging` requirements map to tests and implementation anchors. article Standard

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 2 SpecSection(s) · 1 H2 heading(s)

Section id	Required	Found
what-this-feature-specifies	yes	yes
implementation-anchors	yes	yes

Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).

Related spec docs

• Area
  Compiler integration

  Parent area

• Area
  Resolution and projects

  Project graph logic resolves and injects corelib

• Area
  Stability and API shape

  API stability expectations depend on canonical packaging

• Feature
  Corelib discovery and packaging

  Parent feature hub

Why did a change pass locally but fail in CI?

Most often, one crate boundary changed but the corresponding fixture or downstream consumer was not updated. Re-run the nearest conformance suite and inspect cross-crate handoff points.

Where should I start debugging?

1. Confirm the target requirement in this feature hub.
2. Step through Canonical package root compiler/corelib/beskid_corelib and `Corelib path discovery in `compiler/crates/beskid_analysis/src/projects/graph/resolver.rs.
3. Validate consumer behavior at CLI embedding/install support in compiler/crates/beskid_cli/build.rsandcompiler/crates/beskid_cli/src/corelib_runtime.rs“.
4. Reproduce with Integration checks in compiler/crates/beskid_tests/src/projects/corelib“.

How do I add a new rule safely?

Document the new contract in the relevant article, update implementation in the owning crate, and add a fixture proving both happy-path and failure-path behavior.