@intentius/chant 0.0.2 → 0.0.4

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@intentius/chant",
-  "version": "0.0.2",
+  "version": "0.0.4",
+  "license": "Apache-2.0",
   "type": "module",
   "files": ["src/"],
   "publishConfig": {

package/src/build.ts

@@ -53,6 +53,8 @@ export function partitionByLexicon(
   const partitions = new Map<string, Map<string, Declarable>>();
 
   for (const [name, entity] of entities) {
+    // LexiconOutput instances are collected separately; skip them here
+    if (isLexiconOutput(entity)) continue;
     const lexicon = entity.lexicon;
     if (!partitions.has(lexicon)) {
       partitions.set(lexicon, new Map());
@@ -100,7 +102,18 @@ export function collectLexiconOutputs(
   for (const [name, entity] of entities) {
     if (isLexiconOutput(entity as unknown)) {
       const lexiconOutput = entity as unknown as LexiconOutput;
-      lexiconOutput._setSourceEntity(name);
+      // Resolve source entity name from the WeakRef parent identity
+      const parent = lexiconOutput._sourceParent.deref();
+      let sourceName = name;
+      if (parent) {
+        for (const [entityName, e] of entities) {
+          if (e === parent) {
+            sourceName = entityName;
+            break;
+          }
+        }
+      }
+      lexiconOutput._setSourceEntity(sourceName);
       outputs.push(lexiconOutput);
       continue;
     }

package/src/codegen/docs-interpolation.test.ts

@@ -0,0 +1,77 @@
+import { describe, test, expect, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { expandFileMarkers } from "./docs";
+
+describe("expandFileMarkers", () => {
+  let dir: string;
+
+  beforeAll(() => {
+    dir = mkdtempSync(join(tmpdir(), "docs-interp-"));
+    mkdirSync(join(dir, "sub"), { recursive: true });
+    writeFileSync(
+      join(dir, "example.ts"),
+      'import * as _ from "./_";\n\nexport const bucket = new _.Bucket({\n  bucketName: "test",\n});\n',
+    );
+    writeFileSync(
+      join(dir, "sub", "nested.ts"),
+      "line1\nline2\nline3\nline4\nline5\nline6\nline7\nline8\n",
+    );
+  });
+
+  afterAll(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("expands full file marker", () => {
+    const result = expandFileMarkers("Before\n\n{{file:example.ts}}\n\nAfter", dir);
+    expect(result).toContain('```typescript title="example.ts"');
+    expect(result).toContain('import * as _ from "./_";');
+    expect(result).toContain("```");
+    expect(result).toStartWith("Before\n\n");
+    expect(result).toEndWith("\n\nAfter");
+  });
+
+  test("expands line range", () => {
+    const result = expandFileMarkers("{{file:sub/nested.ts:3-5}}", dir);
+    expect(result).toContain('```typescript title="nested.ts"');
+    expect(result).toContain("line3\nline4\nline5");
+    expect(result).not.toContain("line2");
+    expect(result).not.toContain("line6");
+  });
+
+  test("supports title override", () => {
+    const result = expandFileMarkers("{{file:example.ts|title=my-file.ts}}", dir);
+    expect(result).toContain('```typescript title="my-file.ts"');
+  });
+
+  test("supports line range with title override", () => {
+    const result = expandFileMarkers(
+      "{{file:sub/nested.ts:2-4|title=snippet.ts}}",
+      dir,
+    );
+    expect(result).toContain('```typescript title="snippet.ts"');
+    expect(result).toContain("line2\nline3\nline4");
+  });
+
+  test("throws on missing file", () => {
+    expect(() => expandFileMarkers("{{file:nope.ts}}", dir)).toThrow(
+      /file not found/,
+    );
+  });
+
+  test("leaves content without markers unchanged", () => {
+    const input = "No markers here\n\n```typescript\ncode\n```\n";
+    expect(expandFileMarkers(input, dir)).toBe(input);
+  });
+
+  test("expands multiple markers", () => {
+    const result = expandFileMarkers(
+      "{{file:example.ts}}\n\n{{file:sub/nested.ts:1-2}}",
+      dir,
+    );
+    expect(result).toContain('title="example.ts"');
+    expect(result).toContain('title="nested.ts"');
+  });
+});

package/src/codegen/docs.ts

@@ -39,6 +39,8 @@ export interface DocsConfig {
   srcDir?: string;
   /** Base path for the generated Astro site (e.g. '/lexicons/aws/') */
   basePath?: string;
+  /** Root directory for resolving {{file:...}} markers in extra page content */
+  examplesDir?: string;
 }
 
 export interface DocsResult {
@@ -84,6 +86,66 @@ interface RuleMeta {
   type: "lint" | "post-synth";
 }
 
+// ── File marker interpolation ──────────────────────────────────────
+
+/**
+ * Expand `{{file:path.ts}}` markers in content with fenced code blocks.
+ *
+ * Supported forms:
+ * - `{{file:path.ts}}` — full file
+ * - `{{file:path.ts:5-12}}` — lines 5–12 (1-based, inclusive)
+ * - `{{file:path.ts|title=custom.ts}}` — override the code block title
+ * - `{{file:path.ts:5-12|title=custom.ts}}` — both
+ */
+export function expandFileMarkers(content: string, examplesDir: string): string {
+  return content.replace(
+    /\{\{file:([^}]+)\}\}/g,
+    (_match, spec: string) => {
+      // Parse options after |
+      let filePart = spec;
+      let title: string | undefined;
+      const pipeIdx = spec.indexOf("|");
+      if (pipeIdx !== -1) {
+        filePart = spec.substring(0, pipeIdx);
+        const opts = spec.substring(pipeIdx + 1);
+        const titleMatch = opts.match(/title=([^\s|]+)/);
+        if (titleMatch) title = titleMatch[1];
+      }
+
+      // Parse line range after :digits-digits at end of filePart
+      let lineStart: number | undefined;
+      let lineEnd: number | undefined;
+      const rangeMatch = filePart.match(/^(.+):(\d+)-(\d+)$/);
+      if (rangeMatch) {
+        filePart = rangeMatch[1];
+        lineStart = parseInt(rangeMatch[2], 10);
+        lineEnd = parseInt(rangeMatch[3], 10);
+      }
+
+      const filePath = join(examplesDir, filePart);
+      let fileContent: string;
+      try {
+        fileContent = readFileSync(filePath, "utf-8");
+      } catch {
+        throw new Error(`File marker {{file:${spec}}} — file not found: ${filePath}`);
+      }
+
+      // Extract line range if specified
+      if (lineStart !== undefined && lineEnd !== undefined) {
+        const lines = fileContent.split("\n");
+        fileContent = lines.slice(lineStart - 1, lineEnd).join("\n");
+      }
+
+      // Determine language from extension
+      const ext = filePart.substring(filePart.lastIndexOf(".") + 1);
+      const lang = ext === "ts" || ext === "tsx" ? "typescript" : ext;
+      const displayTitle = title ?? filePart.substring(filePart.lastIndexOf("/") + 1);
+
+      return `\`\`\`${lang} title="${displayTitle}"\n${fileContent.trimEnd()}\n\`\`\``;
+    },
+  );
+}
+
 // ── Pipeline ───────────────────────────────────────────────────────
 
 /**
@@ -137,6 +199,10 @@ export function docsPipeline(config: DocsConfig): DocsResult {
   // Extra pages from lexicon config
   if (config.extraPages) {
     for (const page of config.extraPages) {
+      let content = page.content;
+      if (config.examplesDir) {
+        content = expandFileMarkers(content, config.examplesDir);
+      }
       pages.set(
         `${page.slug}.mdx`,
         [
@@ -145,7 +211,7 @@ export function docsPipeline(config: DocsConfig): DocsResult {
           page.description ? `description: "${page.description}"` : "",
           "---",
           "",
-          page.content,
+          content,
           "",
         ]
           .filter(Boolean)
@@ -300,7 +366,15 @@ function buildSidebar(
   config: DocsConfig,
   result: DocsResult,
 ): Array<Record<string, unknown>> {
+  // Starlight prepends basePath to every sidebar `link`, so a site-root-relative
+  // path like "/chant/" becomes "/chant/lexicons/aws/chant/" — a 404.  Instead
+  // we use relative traversal: "../../" is prepended to become
+  // "/chant/lexicons/aws/../../" which the browser resolves to "/chant/".
+  const segments = (config.basePath ?? "/").replace(/^\/|\/$/g, "").split("/");
+  const backLink = segments.length > 1 ? "../".repeat(segments.length - 1) : "/";
+
   const items: Array<Record<string, unknown>> = [
+    { label: "← chant docs", link: backLink },
     { label: "Overview", slug: "index" },
   ];
 

package/src/discovery/collect.ts

@@ -1,11 +1,14 @@
 import { isDeclarable, type Declarable } from "../declarable";
 import { isCompositeInstance, expandComposite } from "../composite";
+import { isLexiconOutput } from "../lexicon-output";
 import { DiscoveryError } from "../errors";
 
 /**
  * Collects all declarable entities from imported modules.
  * CompositeInstance exports are expanded into individual entities
  * with `{exportName}_{memberName}` naming.
+ * LexiconOutput exports are also collected so that build() can
+ * extract them and pass them to the serializer.
  *
  * @param modules - Array of module records with their exports
  * @returns Map of export name to Declarable entity
@@ -43,6 +46,10 @@ export function collectEntities(
           }
           entities.set(expandedName, entity);
         }
+      } else if (isLexiconOutput(value)) {
+        // LexiconOutput is not a Declarable but build() expects to find them
+        // in the entities map so it can collect and pass them to serializers
+        entities.set(name, value as unknown as Declarable);
       }
     }
   }