feat: HC-116 — @import for .hcs cascade sheets#27
Merged
Conversation
Sheet modularity: a sheet may begin with @import "path.hcs" directives. - Expansion is depth-first at the directive position, so the importing sheet's own rules come later in source order and win specificity ties — the importer overrides what it imports (CSS discipline: imports must precede rules, context blocks and contracts). - Each sheet expands at most once per resolution (diamonds dedupe); a cyclic import is an error naming the chain. - Provenance keeps the file each rule was defined in, so explain and the IR point at the real source across files; contracts compose by the same expansion and still only narrow (an imported baseline's @contract: gates every value the importer sets). - API: ImportHandling (.unsupported default / .syntaxOnly for LSP single-buffer diagnostics / .loader for expansion); the CLI loader resolves targets relative to the importing sheet and reports cwd-relative provenance paths. - Docs: EBNF syntax 0.3 (<import-stmt>), resolution semantics 0.3 (§5.1 sheet composition, normative), RFC 0.3 (§4.2.4), Usage §7 with real outputs, tenant example Examples/imports/acme.hcs. - Version: 0.6.0-dev (new dev cycle). 14 new tests (126 total). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 677d4b0759
ℹ️ 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".
Contributor
There was a problem hiding this comment.
Pull request overview
Adds first-class sheet modularity for .hcs via @import, enabling multi-file cascade sheet configurations while preserving cascade order semantics and provenance across files.
Changes:
- Implement
@importparsing + expansion inCascadeSheetReadervia newImportHandlingAPI (unsupported / syntaxOnly / loader). - Update CLI and diagnostics to use appropriate import handling (
.loaderfor CLI,.syntaxOnlyfor single-buffer diagnostics). - Add comprehensive import-focused tests, docs/spec updates, examples, and bump resolver version to
0.6.0-dev.
Reviewed changes
Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| workplan.md | Marks HC-116 as completed and links to normative semantics. |
| Tests/HypercodeTests/ImportTests.swift | Adds test coverage for import order, depth-first expansion, dedupe, cycles, and cross-file provenance/contracts. |
| Sources/HypercodeCLI/main.swift | Adds readSheet helper to load/expand imported sheets for CLI commands. |
| Sources/Hypercode/Version.swift | Bumps resolver version constant to 0.6.0-dev. |
| Sources/Hypercode/HCS/CascadeSheetReader.swift | Adds ImportHandling and implements import expansion, dedupe, and cycle detection in the reader. |
| Sources/Hypercode/Documentation.docc/Hypercode.md | Documents ImportHandling in the public API list. |
| Sources/Hypercode/Diagnostics/DocumentDiagnostics.swift | Switches cascade-sheet diagnostics to .syntaxOnly import handling. |
| RFC/Hypercode.md | Updates RFC to v0.3 and documents @import semantics. |
| Package.swift | Updates the package version comment to 0.6.0-dev. |
| Examples/imports/acme.hcs | Adds a tenant example demonstrating imports + overrides. |
| EBNF/Hypercode_Syntax.md | Updates syntax spec to include <import-stmt> and import rules. |
| EBNF/Hypercode_Resolution.md | Adds normative import expansion semantics to the resolution spec. |
| DOCS/Usage.md | Adds CLI usage documentation for imports and updates resolver version in example output. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
This was referenced Jun 12, 2026
…, Unreleased changelog - HC3002 dangling-selector warnings carry the rule's defining file, so a dead selector in an imported baseline points at the baseline, not at the entry sheet that imported it. - The entry sheet path goes through the same canonicalization as every import target (standardize + cwd-relativize), so an absolute entry path and a relative import of the same file can no longer get two identities — which previously missed a cycle and expanded the entry sheet twice. - CHANGELOG gains the Unreleased — 0.6.0-dev section the Version.swift comment promises (the EBNF specs keep their own in-file change logs, already updated to 0.3). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…(file:) Residual-risk follow-up on #27: - read(file:imports:) documents that the entry file must use the same canonical identity scheme the loader returns — identity strings are compared verbatim by cycle detection and dedupe; - RFC §8: the import loader is the policy boundary — the CLI loader reads any reachable path (fine for trusted local config), embedding contexts resolving untrusted sheets must supply a policy-bound loader; Usage §7 carries the same line. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Sheet modularity (HC-116): real configurations don't live in one file.
Semantics
@import "path.hcs"directives must precede rules, context blocks and contracts (CSS discipline).!importantmechanism.explainand IR v2 point at the real source across files.@contract:gates every value the importer sets (HC2104).API
ImportHandling:.unsupported(default),.syntaxOnly(LSP single-buffer diagnostics),.loader(expansion; the loader returns a canonical identity used for cycle detection/dedupe). CLI resolves targets relative to the importing sheet, provenance paths reported cwd-relative.Docs
EBNF syntax 0.3 (
<import-stmt>), resolution semantics 0.3 (§5.1, normative), RFC 0.3 (§4.2.4), Usage §7 with real CLI outputs, tenant exampleExamples/imports/acme.hcs. Version bumped to 0.6.0-dev.Tests
14 new (126 total): importer-wins-ties, cross-file provenance, depth-first nesting, diamond dedupe, contract composition (HC2104 across files), direct/indirect cycles, import-after-rule, no-loader, syntaxOnly, unreadable target, malformed directives,
@important[x]:guard non-collision, error-in-imported-sheet file naming.First of the planned train: HC-116 → HC-114 → HC-120 → HC-121.
🤖 Generated with Claude Code