@intentius/chant 0.124.20 → 0.124.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.124.20",
+  "version": "0.124.22",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/codegen/docs-pages.ts

@@ -16,6 +16,7 @@
  * - `group`: a nested subgroup label inside the quadrant (e.g. "Vendor Composites").
  * - `order`: number; lower sorts first within its group. Unordered pages follow, by label.
  * - `hidden`: `true` keeps the page out of the sidebar (reachable by URL only).
+ * - `prompt`: optional `|` block; the agent prompt shown under the title. Kept.
  *
  * `group` / `order` / `hidden` / `label` are stripped from the written copy so
  * Starlight's schema never sees them; `diataxis` stays, and the generated

package/src/codegen/docs-sections.ts

@@ -8,6 +8,13 @@ import { escapeMdx } from "./docs-file-markers";
 import { intrinsicFolds } from "../lexicon";
 import type { DocsConfig, ManifestJSON, MetaEntry, RuleMeta } from "./docs-types";
 
+/** A `prompt: |` block scalar for a page's front matter, or nothing. */
+export function promptFrontmatter(prompt: string | undefined): string[] {
+  const text = prompt?.trim();
+  if (!text) return [];
+  return ["prompt: |", ...text.split("\n").map((line) => (line ? `  ${line}` : ""))];
+}
+
 export function generateOverview(
   config: DocsConfig,
   manifest: ManifestJSON,
@@ -20,6 +27,7 @@ export function generateOverview(
     "---",
     `title: "${config.displayName}"`,
     `description: "${config.description}"`,
+    ...promptFrontmatter(config.prompt),
     "---",
     "",
     config.overview ?? `Reference documentation for the **${config.displayName}** lexicon.`,

package/src/codegen/docs-site/AgentPrompt.astro

@@ -0,0 +1,153 @@
+---
+// "Optional: hand this page to your coding agent": a card under the page title
+// with the first lines of the page's `prompt:` front matter showing, a button
+// that copies the whole prompt, one that copies a link to the card, and a
+// toggle that shows it all. The main docs site and every lexicon docs site
+// render it from their PageTitle override; lexicon sites get a copy of this
+// file from writeDocsSite (docs.ts). The content schema refuses a prompt with
+// no "Never" line. No Starlight import here, so the file works from any site.
+interface Props {
+	text?: string;
+}
+const prompt = (Astro.props.text ?? Astro.locals.starlightRoute?.entry.data.prompt)?.trim();
+---
+{prompt && (
+	<figure class="chant-prompt not-content" id="agent-prompt">
+		<figcaption>Optional: hand this page to your coding agent</figcaption>
+		<details>
+			<summary>
+				<pre class="peek" aria-hidden="true">{prompt}</pre>
+				<span class="more">Show the whole prompt</span>
+			</summary>
+			<pre class="full"><code>{prompt}</code></pre>
+		</details>
+		<div class="actions">
+			<button type="button" class="copy" data-copy={prompt} data-done="Copied">Copy prompt</button>
+			<button type="button" class="link" data-link data-done="Link copied">Copy link</button>
+		</div>
+	</figure>
+)}
+
+<script>
+	const flash = (button: HTMLButtonElement, text: string) => {
+		const was = button.textContent;
+		button.textContent = text;
+		setTimeout(() => (button.textContent = was), 1600);
+	};
+	for (const button of document.querySelectorAll<HTMLButtonElement>('.chant-prompt button')) {
+		button.addEventListener('click', async () => {
+			const card = button.closest('figure')!;
+			const text = button.dataset.link !== undefined ? `${location.origin}${location.pathname}#${card.id}` : (button.dataset.copy ?? '');
+			try {
+				await navigator.clipboard.writeText(text);
+				flash(button, button.dataset.done ?? 'Copied');
+			} catch {
+				// No clipboard (an insecure origin, a denied permission): open the
+				// prompt and select it so the reader can copy it by hand.
+				card.querySelector('details')?.setAttribute('open', '');
+				const code = card.querySelector('.full code');
+				if (code) window.getSelection()?.selectAllChildren(code);
+				flash(button, 'Selected');
+			}
+		});
+	}
+</script>
+
+<style>
+	/* Minimal: zinc greys from Starlight's scale and one blue. */
+	.chant-prompt {
+		--chant-prompt-blue: #2563eb;
+		margin: 1.25rem 0 0;
+		width: min(100%, 44rem);
+		border: 1px solid var(--sl-color-gray-5);
+		border-left: 2px solid var(--chant-prompt-blue);
+		border-radius: 0.5rem;
+		background: var(--sl-color-gray-7, var(--sl-color-black));
+		overflow: hidden;
+	}
+	:global([data-theme='dark']) .chant-prompt {
+		--chant-prompt-blue: #60a5fa;
+	}
+	figcaption {
+		padding: 0.7rem 1rem 0.4rem;
+		font-size: 0.85rem;
+		font-weight: 600;
+		color: var(--sl-color-white);
+	}
+	summary {
+		display: block;
+		list-style: none;
+		cursor: pointer;
+		padding: 0 1rem;
+	}
+	summary::-webkit-details-marker {
+		display: none;
+	}
+	pre {
+		margin: 0;
+		font-family: var(--sl-font-mono);
+		font-size: 0.75rem;
+		line-height: 1.55;
+		color: var(--sl-color-gray-2);
+		white-space: pre-wrap;
+		overflow-wrap: anywhere;
+		background: none;
+		border: 0;
+		padding: 0;
+	}
+	/* Two lines of the prompt, fading out, say it is there. */
+	.peek {
+		max-height: 2.4rem;
+		overflow: hidden;
+		mask-image: linear-gradient(to bottom, #000 40%, transparent);
+	}
+	.more,
+	details[open] summary::after {
+		display: inline-block;
+		margin-top: 0.2rem;
+		font-size: 0.72rem;
+		color: var(--chant-prompt-blue);
+	}
+	details[open] .peek,
+	details[open] .more {
+		display: none;
+	}
+	details[open] summary::after {
+		content: 'Hide the prompt';
+	}
+	.full {
+		padding: 0.25rem 1rem 0;
+	}
+	.actions {
+		display: flex;
+		gap: 0.5rem;
+		padding: 0.7rem 1rem 0.8rem;
+	}
+	button {
+		font: inherit;
+		font-size: 0.78rem;
+		font-weight: 600;
+		border-radius: 0.4rem;
+		padding: 0.35rem 0.85rem;
+		cursor: pointer;
+	}
+	.copy {
+		color: #fff;
+		background: var(--chant-prompt-blue);
+		border: 1px solid var(--chant-prompt-blue);
+	}
+	:global([data-theme='dark']) .copy {
+		color: #09090b;
+	}
+	.copy:hover {
+		filter: brightness(1.1);
+	}
+	.link {
+		color: var(--sl-color-white);
+		background: none;
+		border: 1px solid var(--sl-color-gray-5);
+	}
+	.link:hover {
+		border-color: var(--chant-prompt-blue);
+	}
+</style>

package/src/codegen/docs-types.ts

@@ -21,6 +21,13 @@ export interface DocsConfig {
   packageJsonPath?: string;
   /** Lexicon-specific overview content (markdown) */
   overview?: string;
+  /**
+   * The overview page's agent prompt: "Optional: hand this page to your coding
+   * agent", shown under the title (docs-site/AgentPrompt.astro). Imperative
+   * steps, what to report back, and a line starting "Never". An authored page
+   * under `pagesDir` carries its own as a `prompt:` front-matter field.
+   */
+  prompt?: string;
   /** Output format description (e.g. "CloudFormation JSON template") */
   outputFormat?: string;
   /** Custom service grouping from resource type (e.g. "AWS::S3::Bucket" → "S3") */

package/src/codegen/docs.ts

@@ -390,6 +390,13 @@ export const collections = {
       extend: z.object({
         // Diátaxis quadrant (https://diataxis.fr), chant #1731.
         diataxis: z.enum(['tutorial', 'how-to', 'reference', 'explanation']).optional(),
+        // "Optional: hand this page to your coding agent", shown under the
+        // title by src/components/AgentPrompt.astro. It has to say what the
+        // agent must never do.
+        prompt: z
+          .string()
+          .optional()
+          .refine((p) => !p || /^Never\\b/m.test(p), 'a prompt needs a line that starts with "Never" (what the agent must not do)'),
       }),
     }),
   }),
@@ -404,6 +411,25 @@ export const collections = {
   );
   copyFileSync(pluginSrcPath, join(outDir, "src", "rehype-base-url.mjs"));
 
+  // src/components/: the agent prompt card from chant core, and a PageTitle
+  // override that puts it under Starlight's title on every page with a `prompt:`.
+  mkdirSync(join(outDir, "src", "components"), { recursive: true });
+  copyFileSync(
+    fileURLToPath(new URL("./docs-site/AgentPrompt.astro", import.meta.url)),
+    join(outDir, "src", "components", "AgentPrompt.astro"),
+  );
+  writeFileSync(
+    join(outDir, "src", "components", "PageTitle.astro"),
+    `---
+// Generated by chant's writeDocsSite. Starlight's page title, then the page's agent prompt.
+import Default from '@astrojs/starlight/components/PageTitle.astro';
+import AgentPrompt from './AgentPrompt.astro';
+---
+<Default />
+<AgentPrompt />
+`,
+  );
+
   // astro.config.mjs
   const rehypeLine = config.basePath
     ? `\n  markdown: {\n    rehypePlugins: [[rehypeBaseUrl, { base: '${config.basePath}', projectBase: '/chant' }]],\n  },`
@@ -419,6 +445,7 @@ export default defineConfig({${config.basePath ? `\n  base: '${config.basePath}'
   integrations: [
     starlight({
       title: '${config.displayName}',
+      components: { PageTitle: './src/components/PageTitle.astro' },
       sidebar: ${JSON.stringify(sidebar, null, 6).replace(/\n/g, "\n      ")},
     }),
   ],

package/src/fold/subset.ts

@@ -141,7 +141,9 @@ import { intrinsicCallFolds, intrinsicCallFoldsEagerly, type IntrinsicDef } from
  *      (`{...n}`) is shape-valid (`n` is a plain identifier) but `fold()`
  *      rejects it once it discovers `n` folds to a number, not an object.
  *      Only real evaluation catches this; EVL004 independently narrows
- *      spread sources to a stricter "traceable to a const" shape, which
+ *      spread sources to a stricter "traceable to a const" shape (a const
+ *      declared in the file, or an imported binding, which fold() resolves
+ *      from the exporting module's folded value), which
  *      catches most real-world misuse without evaluating, but is not a
  *      full substitute.
  *

package/src/lint/rules/evl004-spread-non-const.test.ts

@@ -36,6 +36,24 @@ describe("EVL004: spread-non-const", () => {
     expect(evl004SpreadNonConstRule.check(ctx)).toHaveLength(0);
   });
 
+  test("allows spread from an imported binding (named, default, namespace member)", () => {
+    const ctx = createContext(`
+      import base, { steps } from "./shared";
+      import * as shared from "./shared";
+      const x = { ...base, ...shared.preset };
+      const y = [...steps, { run: "true" }];
+    `);
+    expect(evl004SpreadNonConstRule.check(ctx)).toHaveLength(0);
+  });
+
+  test("still flags a call on an imported function", () => {
+    const ctx = createContext(`
+      import { makeSteps } from "./shared";
+      const y = [...makeSteps("web")];
+    `);
+    expect(evl004SpreadNonConstRule.check(ctx)).toHaveLength(1);
+  });
+
   test("flags spread from let variable", () => {
     const ctx = createContext(`
       let base = { a: 1 };

package/src/lint/rules/evl004-spread-non-const.ts

@@ -8,6 +8,11 @@ import { isInsideCompositeFactory } from "./composite-scope";
  * Spread expressions ({...x} or [...x]) must reference a const-declared
  * variable, object literal, or property access chain from a const.
  * Spreading from function calls or non-traceable sources is blocked.
+ *
+ * A binding imported from another module counts as const: an import can't
+ * be reassigned, and sharing an exported const (a preset, a list of
+ * Dockerfile steps) across modules is the point of exporting it. Whether the
+ * exporting module declared it `const` is that module's own EVL concern.
  */
 
 function isTraceableToConst(node: ts.Node, sourceFile: ts.SourceFile): boolean {
@@ -40,8 +45,18 @@ function isTraceableToConst(node: ts.Node, sourceFile: ts.SourceFile): boolean {
 }
 
 function isConstIdentifier(id: ts.Identifier, sourceFile: ts.SourceFile): boolean {
-  // Walk all statements looking for a const declaration of this identifier
+  // Walk all statements looking for a const declaration or an import of this identifier
   for (const stmt of sourceFile.statements) {
+    if (ts.isImportDeclaration(stmt) && stmt.importClause && !stmt.importClause.isTypeOnly) {
+      const clause = stmt.importClause;
+      if (clause.name?.text === id.text) return true;
+      const bindings = clause.namedBindings;
+      if (bindings && ts.isNamedImports(bindings)) {
+        if (bindings.elements.some((el) => !el.isTypeOnly && el.name.text === id.text)) return true;
+      } else if (bindings && ts.isNamespaceImport(bindings) && bindings.name.text === id.text) {
+        return true;
+      }
+    }
     if (ts.isVariableStatement(stmt)) {
       if (stmt.declarationList.flags & ts.NodeFlags.Const) {
         for (const decl of stmt.declarationList.declarations) {