Skip to content

fix: sync linked-resource path resolution #25

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
NejcS merged 1 commit into from
Sep 28, 2026
Merged

fix: sync linked-resource path resolution #25

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions forge/rules/linked-resources.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,9 @@ A linked resource **must not** be any of the following:
```

## File location and path resolution
- Paths are resolved relative to the directory where `codeplain` is run (the current working directory)
- Paths are resolved against the directory that contains the `.plain` file passed to `codeplain`, not the directory where `codeplain` is run
- This includes links inside imported and required modules — they resolve against that same directory, not against the directory the imported module itself lives in
- A path that does not resolve there is then looked up in the `--template-dir` directory (if given), and last in the built-in `standard_template_library`
- Because the `.plain` file's own directory is the anchor, a render gives the same result from any working directory
- Relative paths may traverse into parent directories — `[resource](../../resources/resource.md)` is valid — as long as they resolve to a real text file on disk
- The conventional location is a `resources/` directory; keep the resource inside the project so the path stays stable from wherever `codeplain` is run
- The conventional location is a `resources/` directory next to the `.plain` file
8 changes: 5 additions & 3 deletions forge/skills/add-resource/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,9 @@ Use standard markdown link syntax inside any spec section:

## Path Rules

- Paths are resolved **relative to the directory where `codeplain` is run** (the current working directory).
- Paths are resolved **against the directory that contains the `.plain` file passed to `codeplain`**, not the directory where `codeplain` is run.
- This includes links inside imported and required modules — they resolve against that same directory, not against the directory the imported module itself lives in.
- A path that does not resolve there is then looked up in the `--template-dir` directory (if given), and last in the built-in `standard_template_library`.
- Relative paths may traverse into parent directories — `[resource](../../resources/resource.md)` is valid — as long as they resolve to a real text file on disk.
- **No external URLs** — only local file references.
- **No folder paths** — the target must be a file, not a directory.
Expand Down Expand Up @@ -69,7 +71,7 @@ The **only** exceptions are URLs and paths that are *values the produced softwar

### What a linked resource CAN be

- A single file inside the project, reachable by a path relative to where `codeplain` is run — parent-directory traversal (`../`) is allowed (`resources/` is the conventional home).
- A single file inside the project, reachable by a path relative to the `.plain` file — parent-directory traversal (`../`) is allowed (`resources/` is the conventional home).
- A **text-based** file the renderer can read end-to-end: JSON, YAML, XML, HTML, Markdown, plain text, CSV, TSV, source code in any language (`.py`, `.js`, `.ts`, `.go`, `.java`, `.rb`, `.rs`, `.kt`, `.swift`, `.c`, `.cpp`, `.cs`, …), shell scripts, SQL, JSON Schema, OpenAPI, AsyncAPI, Protobuf `.proto`, GraphQL SDL, `.jolt`, `.env.example`, `.toml`, `.ini`, `.proto`, `Dockerfile`, etc.

## Common Resource Types
Expand Down Expand Up @@ -101,6 +103,6 @@ The **only** exceptions are URLs and paths that are *values the produced softwar
- [ ] **Target is a text-based file** (no binary extensions: `.png`, `.jpg`, `.jpeg`, `.gif`, `.bmp`, `.tiff`, `.webp`, `.ico`, `.pdf`, `.docx`, `.xlsx`, `.pptx`, `.zip`, `.tar`, `.gz`, `.mp3`, `.mp4`, `.wav`, `.exe`, `.so`, `.dylib`, `.class`, `.wasm`, …)
- [ ] **No URLs or folder paths anywhere in the surrounding `.plain` content** (not as link targets, not in body prose), with the sole exception of URLs / paths that are runtime values the generated software itself uses
- [ ] Path is relative to the `.plain` file, not absolute
- [ ] Path resolves to a real text file on disk from where `codeplain` is run (`../` traversal is allowed)
- [ ] Path resolves to a real text file on disk relative to the `.plain` file (`../` traversal is allowed)
- [ ] Markdown link syntax is correct: `[display text](relative/path)`
- [ ] Resource content is relevant and adds value beyond what the spec text says
Loading