@intentius/chant 0.124.12 → 0.124.14

package/dist/lexicon-module.js

@@ -0,0 +1,241 @@
+/**
+ * Lexicons declared by module path (chant #2520).
+ *
+ * A `lexicons` entry has always been a bare name, and chant resolves a name to
+ * the package `@intentius/chant-lexicon-<name>`. A project that writes its own
+ * lexicon in the same repo can instead point at the module:
+ *
+ * ```ts
+ * export default {
+ *   lexicons: ["fly", { name: "site", module: "./lexicon/index.ts" }],
+ * } satisfies ChantConfig;
+ * ```
+ *
+ * The path is resolved against the directory holding `chant.config.ts`. That
+ * module is the whole lexicon: its `LexiconPlugin` export is the plugin, the
+ * plugin's `activities()` and `activityContracts()` members stand in for the
+ * `op/activities` and `op/activity-contracts` subpaths, a `CapabilityPlugin`
+ * export feeds the capability registry, and an `evaluateGatePolicy` export
+ * stands in for the `gate-policy` subpath.
+ *
+ * Loaders take lexicon names, so the config loader records each path-declared
+ * name here and every loader asks {@link lexiconModulePath} before falling back
+ * to the package name. A name declared as a plain string is never recorded, so
+ * a project that names lexicons by package takes exactly the path it always did.
+ */
+import { createRequire } from "node:module";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { ensureTypeScriptLoader } from "./ts-loader.js";
+/** The lexicon name an entry declares, whichever form it takes. */
+export function lexiconDeclarationName(entry) {
+    return typeof entry === "string" ? entry : entry.name;
+}
+export function lexiconNames(entries) {
+    return entries?.map(lexiconDeclarationName);
+}
+/** Name to absolute module path, for the lexicons declared by path in the configs loaded so far. */
+const modulePaths = new Map();
+/** Name to the absolute directory fold trusts for that lexicon (chant#2590). Absent: only the module is trusted. */
+const moduleRoots = new Map();
+/** True when `path` is `dir` itself or lies under it. Both are absolute. */
+function isWithin(path, dir) {
+    const rel = relative(dir, path);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+/**
+ * chant#2590 — the directory fold trusts for a lexicon declared by path.
+ *
+ * A package has a root that bounds its subpaths. A module path has none, so
+ * the directory is either the one `root` names, resolved like `module`, or the
+ * module's own directory. It must lie inside the project (`baseDir`, the
+ * directory holding `chant.config.ts`) and must not contain the project's
+ * source directory (`sourceDir`, relative to `baseDir`, default `.`). The
+ * module must lie inside it.
+ *
+ * Returns the directory, or `undefined` when only the module file is trusted.
+ * A declared `root` that breaks a rule returns a `problem` to report; the
+ * module's own directory breaking one (a module at the project root, say)
+ * just leaves the lexicon with its module file.
+ */
+export function pathLexiconRoot(entry, baseDir, sourceDir = ".") {
+    const modulePath = isAbsolute(entry.module) ? entry.module : resolve(baseDir, entry.module);
+    const declared = entry.root !== undefined;
+    const candidate = declared
+        ? isAbsolute(entry.root)
+            ? resolve(entry.root)
+            : resolve(baseDir, entry.root)
+        : dirname(modulePath);
+    const project = resolve(baseDir);
+    const source = resolve(baseDir, sourceDir);
+    let problem;
+    if (!isWithin(candidate, project))
+        problem = `${candidate} is outside the project (${project})`;
+    else if (isWithin(source, candidate))
+        problem = `${candidate} contains the project's source directory (${source})`;
+    else if (!isWithin(modulePath, candidate))
+        problem = `the module ${modulePath} is not inside ${candidate}`;
+    if (problem === undefined)
+        return { root: candidate };
+    return declared ? { problem } : {};
+}
+/**
+ * Record the path-declared entries of one loaded config. `baseDir` is the
+ * directory the config file sits in. A plain-string entry for a name removes
+ * any path recorded for it earlier in this process, so loading a second
+ * project (the example harness does) cannot leave the first one's module in
+ * place of a package.
+ *
+ * Returns the recorded name-to-path map for this config, empty when every
+ * entry is a plain name.
+ */
+export function registerLexiconDeclarations(entries, baseDir, sourceDir) {
+    const recorded = {};
+    for (const entry of entries ?? []) {
+        if (typeof entry === "string") {
+            modulePaths.delete(entry);
+            moduleRoots.delete(entry);
+            continue;
+        }
+        const path = declaredModulePath(entry, baseDir);
+        modulePaths.set(entry.name, path);
+        recorded[entry.name] = path;
+        const { root } = pathLexiconRoot(entry, baseDir, sourceDir);
+        if (root === undefined)
+            moduleRoots.delete(entry.name);
+        else
+            moduleRoots.set(entry.name, root);
+    }
+    return recorded;
+}
+function declaredModulePath(entry, baseDir) {
+    return isAbsolute(entry.module) ? entry.module : resolve(baseDir, entry.module);
+}
+/**
+ * chant#2589 — the name-to-path map `entries` declare, without recording it.
+ * For a caller that must name path lexicons in its messages but must never
+ * let a loader import one (`chant audit` runs no project code).
+ */
+export function pathLexiconMap(entries, baseDir) {
+    const map = new Map();
+    for (const entry of entries) {
+        if (typeof entry !== "string")
+            map.set(entry.name, declaredModulePath(entry, baseDir));
+    }
+    return map;
+}
+/** A copy of the paths recorded so far in this process. */
+export function recordedLexiconModules() {
+    return new Map(modulePaths);
+}
+/** The absolute module path `name` was declared with, or `undefined` for a package-backed lexicon. */
+export function lexiconModulePath(name) {
+    return modulePaths.get(name);
+}
+/**
+ * chant#2590 — the directory fold trusts for a path-declared lexicon, or
+ * `undefined` when only its module file is trusted (or `name` is package-backed).
+ * See {@link pathLexiconRoot}.
+ */
+export function lexiconModuleRoot(name) {
+    return moduleRoots.get(name);
+}
+/** Forget every recorded path. For tests. */
+export function resetLexiconModules() {
+    modulePaths.clear();
+    moduleRoots.clear();
+}
+/**
+ * Import the module a path-declared lexicon names. Returns `undefined` when
+ * `name` is package-backed, so a caller falls through to its package import.
+ * An import failure is thrown with the declared path in the message.
+ */
+export async function importLexiconModule(name) {
+    const path = modulePaths.get(name);
+    if (path === undefined)
+        return undefined;
+    try {
+        ensureTypeScriptLoader();
+        return (await import(path));
+    }
+    catch (err) {
+        throw new Error(`lexicon "${name}" is declared with module ${path}, which could not be loaded: ` +
+            (err instanceof Error ? err.message : String(err)));
+    }
+}
+/**
+ * chant#2578 — how a message should name a lexicon. A package-backed name is
+ * its npm package; a lexicon declared by path is that path, relative to
+ * `fromDir` when it sits under it. `paths` defaults to the paths recorded in
+ * this process; see {@link pathLexiconMap} for a map that is not recorded.
+ */
+export function lexiconSourceLabel(name, fromDir = process.cwd(), paths = modulePaths) {
+    const path = paths.get(name);
+    if (path === undefined)
+        return `@intentius/chant-lexicon-${name}`;
+    const rel = relative(fromDir, path);
+    return rel === "" || rel.startsWith("..") || isAbsolute(rel) ? path : `./${rel.split(sep).join("/")}`;
+}
+/**
+ * The npm packages that provide `names`, leaving out every lexicon declared by
+ * path: those have nothing to install. `paths` as in {@link lexiconSourceLabel}.
+ */
+export function lexiconPackagesToInstall(names, paths = modulePaths) {
+    return names.filter((name) => !paths.has(name)).map((name) => `@intentius/chant-lexicon-${name}`);
+}
+/**
+ * chant#2845 — the npm package a bare specifier names: `@scope/name` for a
+ * scoped one, else its first segment. `undefined` for a relative or absolute
+ * path, which is not a package.
+ */
+export function packageNameOf(spec) {
+    if (spec.startsWith(".") || isAbsolute(spec) || spec.startsWith("file:"))
+        return undefined;
+    const parts = spec.split("/");
+    return spec.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
+}
+/** True when `err` says the package `pkg` itself could not be found, not something it imports. */
+function isPackageNotFound(err, pkg) {
+    const code = err?.code;
+    if (code !== "ERR_MODULE_NOT_FOUND" && code !== "MODULE_NOT_FOUND")
+        return false;
+    const message = err instanceof Error ? err.message : String(err);
+    return message.includes(`'${pkg}'`) || message.includes(`"${pkg}"`) || message.includes(`${pkg}/`);
+}
+/**
+ * chant#2845 — resolve `spec` (a lexicon package or one of its subpaths) from
+ * `fromDir` instead of from chant's own install, or `undefined` when the
+ * project doesn't have it either.
+ */
+export function resolveFromProject(spec, fromDir = process.cwd()) {
+    try {
+        return createRequire(join(fromDir, "package.json")).resolve(spec);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * chant#2845 — import a lexicon package, or one of its subpaths, by its bare
+ * specifier. chant's own install is tried first, as a bare `import()` always
+ * did, so a lexicon chant can reach loads exactly as before. When the package
+ * isn't there, which is the case for a chant installed globally and a project
+ * that installs its lexicons in its own node_modules, it is resolved from
+ * `fromDir` (the project) and imported from there. Any other failure, and a
+ * package the project doesn't have either, rethrows the first error.
+ */
+export async function importLexiconPackage(spec, fromDir = process.cwd()) {
+    try {
+        ensureTypeScriptLoader();
+        return (await import(spec));
+    }
+    catch (err) {
+        const pkg = packageNameOf(spec);
+        if (pkg === undefined || !isPackageNotFound(err, pkg))
+            throw err;
+        const resolved = resolveFromProject(spec, fromDir);
+        if (resolved === undefined)
+            throw err;
+        return (await import(pathToFileURL(resolved).href));
+    }
+}

package/dist/lexicon-output.js

@@ -0,0 +1,218 @@
+var _a;
+import { INTRINSIC_MARKER, isIntrinsic } from "./intrinsic.js";
+import { isAttrRefLike } from "./utils.js";
+/**
+ * Marker symbol for LexiconOutput identification (chant #1122).
+ *
+ * A GLOBAL symbol (via `Symbol.for`), like every other chant-core brand
+ * check — `DECLARABLE_MARKER`, `STACK_OUTPUT_MARKER`, `INTRINSIC_MARKER` —
+ * holds across separately-loaded copies of chant-core the way `instanceof`
+ * does not. Two copies in one process is a plain npm-dedupe outcome: a
+ * lexicon pinned to a chant range that does not overlap the project's own
+ * gets a nested `node_modules/@intentius/chant`, and a project file
+ * importing `output` from that lexicon then holds a different `LexiconOutput`
+ * class than the CLI does. `instanceof LexiconOutput` returns false for a
+ * real output built by the other copy, and every `Outputs` entry vanishes
+ * silently.
+ *
+ * Installed non-enumerably in the constructor (not as a public class field)
+ * so a shallow spread/clone of a real instance — which would already lack
+ * its prototype methods (`getOutputValue()`, `_setSourceEntity()`, …) — does
+ * not silently pick up the marker and pass this guard too.
+ */
+export const LEXICON_OUTPUT_MARKER = Symbol.for("chant.lexiconOutput");
+/**
+ * Sanitize auto-generated Output name parts into a valid CloudFormation
+ * logical id. Real CloudFormation logical ids (including `Outputs` keys)
+ * must match `^[A-Za-z0-9]+$` — no dots, underscores, or other punctuation.
+ *
+ * Splits every part on runs of non-alphanumeric characters (dots from a
+ * nested `Fn::GetAtt` attribute path, underscores, hyphens, etc.) and
+ * re-joins the resulting segments in camelCase. This keeps the id
+ * deterministic and unique per (entityName, attribute) pair while
+ * discarding only punctuation — no information is lost, so two distinct
+ * inputs only collide if they already differ solely by punctuation.
+ *
+ * @internal
+ */
+export function sanitizeLogicalId(...parts) {
+    const segments = parts
+        .join("_")
+        .split(/[^A-Za-z0-9]+/)
+        .filter((segment) => segment.length > 0);
+    if (segments.length === 0)
+        return "Output";
+    return segments
+        .map((segment, i) => (i === 0 ? segment : segment.charAt(0).toUpperCase() + segment.slice(1)))
+        .join("");
+}
+/**
+ * Represents a cross-lexicon output that bridges a producing lexicon (e.g. AWS)
+ * with any consuming lexicon (e.g. GitHub, Cloudflare).
+ *
+ * Implements Intrinsic so it can be used as Value<string> anywhere.
+ *
+ * Accepts an AttrRef (resource attribute reference), any Intrinsic (e.g. Sub,
+ * Join) for computed output values like constructed URLs, or an already-
+ * resolved literal (string/number/boolean) — a constant the author's code
+ * computed rather than a reference to anything (chant #1121).
+ */
+export class LexiconOutput {
+    constructor(ref, name) {
+        this[_a] = true;
+        Object.defineProperty(this, LEXICON_OUTPUT_MARKER, {
+            value: true,
+            enumerable: false,
+        });
+        // Duck-type, not `instanceof` (chant #1137): a lexicon built against a
+        // separate copy of `@intentius/chant` produces AttrRefs that fail
+        // `instanceof AttrRef` here but carry the same shape — and since AttrRef
+        // also implements Intrinsic, missing this branch does not fail loud.
+        // The value instead falls into the `isIntrinsic(ref)` branch below,
+        // stored as `_intrinsic` rather than an AttrRef-sourced output, so
+        // `getOutputValue()` later calls the foreign AttrRef's own `toJSON()`
+        // (the `{__attrRef}` wire envelope) instead of emitting `Fn::GetAtt` —
+        // a broken Output emitted with no error at synth time.
+        if (isAttrRefLike(ref)) {
+            const parent = ref.parent.deref();
+            if (!parent) {
+                throw new Error("Cannot create LexiconOutput: parent entity has been garbage collected");
+            }
+            if (!("lexicon" in parent) || typeof parent.lexicon !== "string") {
+                throw new Error("Cannot create LexiconOutput: parent entity has no lexicon field");
+            }
+            this.sourceLexicon = parent.lexicon;
+            this.sourceEntity = "";
+            this.sourceAttribute = ref.attribute;
+            this.outputName = name;
+            this._sourceParent = ref.parent;
+            this._intrinsic = null;
+            this._literalValue = null;
+        }
+        else if (isIntrinsic(ref)) {
+            // Intrinsic (Sub, Join, Ref, etc.) — no parent entity tracking needed.
+            this.sourceLexicon = "";
+            this.sourceEntity = "";
+            this.sourceAttribute = null;
+            this.outputName = name;
+            this._sourceParent = null;
+            this._intrinsic = ref;
+            this._literalValue = null;
+        }
+        else if (typeof ref === "string" || typeof ref === "number" || typeof ref === "boolean") {
+            // An already-resolved literal — a real string/number/boolean the
+            // caller computed (a prop, a template string, a plain constant), not
+            // a reference to anything. The `string` arm of the exported type
+            // exists for a documented reason: a generated resource's attribute
+            // accessor is typed `string` at the TypeScript level but is a real
+            // `AttrRef` at runtime, caught by the `isAttrRefLike` check above — so
+            // anything that reaches this branch genuinely has no source entity
+            // or attribute, and is recorded to be emitted as a plain `Value`
+            // rather than a fabricated `Fn::GetAtt` (chant #1121).
+            this.sourceLexicon = "";
+            this.sourceEntity = "";
+            this.sourceAttribute = null;
+            this.outputName = name;
+            this._sourceParent = null;
+            this._intrinsic = null;
+            this._literalValue = ref;
+        }
+        else {
+            // Neither a reference NOR a resolved value — most commonly `undefined`
+            // from accessing a resource member that looks like an attribute but
+            // isn't one (a typo, or a genuine prop that was never wired onto the
+            // instance as either an AttrRef or an echoed literal). Silently
+            // treating this as a literal would trade one invalid Output (a
+            // fabricated `Fn::GetAtt`) for another (a `Value` that is missing or
+            // `null`) — fail loudly instead, the same call `stackOutput()` already
+            // makes for a ref it cannot anchor (chant #1121).
+            throw new Error(`output(ref, "${name}"): ref must be an AttrRef, an Intrinsic, or an already-resolved string/number/boolean — got ${ref === null ? "null" : typeof ref} instead. If this came from a resource member access (e.g. "resource.SomeField"), that member is neither a generated attribute nor a real value here — check for a typo or a property that CloudFormation does not expose via Fn::GetAtt.`);
+        }
+    }
+    /**
+     * Set the source entity logical name.
+     * Called during build when entity names are resolved.
+     * @internal
+     */
+    _setSourceEntity(name) {
+        this.sourceEntity = name;
+    }
+    /**
+     * Returns the CloudFormation Output Value for this output.
+     * For a literal output: the resolved value itself, verbatim.
+     * For AttrRef-based outputs: emits Fn::GetAtt.
+     * For Intrinsic-based outputs: delegates to the intrinsic's toJSON().
+     */
+    getOutputValue() {
+        if (this._literalValue !== null) {
+            return this._literalValue;
+        }
+        if (this._intrinsic) {
+            return this._intrinsic.toJSON();
+        }
+        return { "Fn::GetAtt": [this.sourceEntity, this.sourceAttribute] };
+    }
+    /**
+     * Create a LexiconOutput with an auto-generated name from entity name and attribute.
+     * Used during cross-lexicon ref auto-detection.
+     *
+     * The name is sanitized to a valid CloudFormation logical id (see
+     * {@link sanitizeLogicalId}) since it is used verbatim as the `Outputs`
+     * key by lexicon serializers (e.g. AWS CloudFormation), which reject
+     * dots or underscores in logical ids.
+     *
+     * @param ref - The AttrRef pointing to the source entity
+     * @param entityName - The logical name of the source entity
+     * @returns A LexiconOutput with a name derived from `{entityName}{Attribute}`
+     */
+    static auto(ref, entityName) {
+        const name = sanitizeLogicalId(entityName, ref.attribute);
+        const output = new LexiconOutput(ref, name);
+        output._setSourceEntity(entityName);
+        return output;
+    }
+    toJSON() {
+        return { "chant::output": this.outputName };
+    }
+}
+_a = INTRINSIC_MARKER;
+/**
+ * Create a LexiconOutput from an AttrRef, an Intrinsic, or an already-
+ * resolved literal, and a user-provided output name.
+ *
+ * Usage with AttrRef:
+ * ```ts
+ * const bucketArn = output(dataBucket.arn, "DataBucketArn");
+ * ```
+ *
+ * Usage with an intrinsic (e.g. a constructed URL):
+ * ```ts
+ * const solrUrl = output(Sub`http://${Ref(albDnsName)}/solr`, "solrUrl");
+ * ```
+ *
+ * Usage with a literal (chant #1121) — a real value the caller already
+ * computed, not a reference:
+ * ```ts
+ * const apiVersion = output("v1", "ApiVersion");
+ * ```
+ */
+export function output(ref, name) {
+    return new LexiconOutput(ref, name);
+}
+/**
+ * Type guard to check if a value is a LexiconOutput.
+ *
+ * Structural, not `instanceof` (chant #1122) — keys off {@link
+ * LEXICON_OUTPUT_MARKER}, a global symbol, so it holds across separately-
+ * loaded copies of chant-core the way `instanceof` does not. Every caller
+ * (`collect.ts`, `build.ts`, `graph-ir.ts`, `entity-wire-codec.ts`) reads
+ * only own-prototype members off the result (`outputName`, `_sourceParent`,
+ * `_setSourceEntity()`, `getOutputValue()`), all of which work identically
+ * on a cross-copy instance.
+ */
+export function isLexiconOutput(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        LEXICON_OUTPUT_MARKER in value &&
+        value[LEXICON_OUTPUT_MARKER] === true);
+}

package/dist/lexicon-plugin-helpers.js

@@ -0,0 +1,104 @@
+/**
+ * Shared helpers for lexicon plugin implementations.
+ *
+ * Eliminates boilerplate across the 15 lexicon plugins that use it by providing
+ * factory functions for common plugin methods: skills loading,
+ * MCP diff tool, and MCP catalog resource.
+ */
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+/**
+ * Create a skills loader that reads .md files from a lexicon's skills directory.
+ *
+ * Usage in a plugin:
+ * ```ts
+ * import { createSkillsLoader } from "@intentius/chant/lexicon-plugin-helpers";
+ *
+ * const loadSkills = createSkillsLoader(import.meta.url, [
+ *   { file: "chant-aws.md", name: "chant-aws", description: "..." },
+ * ]);
+ *
+ * // In plugin:
+ * skills() { return loadSkills(); }
+ * ```
+ */
+export function createSkillsLoader(importMetaUrl, specs) {
+    return () => {
+        const skillsDir = join(dirname(fileURLToPath(importMetaUrl)), "skills");
+        return specs.map(({ file, ...meta }) => {
+            try {
+                const content = readFileSync(join(skillsDir, file), "utf-8");
+                return { ...meta, content };
+            }
+            catch {
+                return { ...meta, content: "" };
+            }
+        });
+    };
+}
+// ── MCP Diff Tool ─────────────────────────────────────────────────
+/**
+ * Create an MCP diff tool contribution for a lexicon.
+ *
+ * All lexicons (except Azure) expose an identical-shape "diff" tool that
+ * compares current build output against previous output using the lexicon's
+ * serializer. The tool name is namespaced by `lexiconName` (e.g. `gcp:diff`)
+ * so multiple lexicons loaded together don't collide on the same tool key.
+ */
+export function createDiffTool(serializer, description, lexiconName) {
+    return {
+        name: `${lexiconName}:diff`,
+        description,
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Path to the infrastructure project directory",
+                },
+            },
+        },
+        async handler(params) {
+            const { diffCommand } = await import("./cli/commands/diff.js");
+            const result = await diffCommand({
+                path: params.path ?? ".",
+                serializers: [serializer],
+            });
+            return result;
+        },
+    };
+}
+// ── MCP Catalog Resource ──────────────────────────────────────────
+/**
+ * Create an MCP resource that serves the lexicon's meta.json as a catalog.
+ *
+ * Most lexicons expose a "resource-catalog" resource with identical
+ * structure. The URI is namespaced by `lexiconName` (e.g.
+ * `gcp:resource-catalog`) so multiple lexicons loaded together don't
+ * collide on the same resource key.
+ *
+ * @param importMetaUrl — The plugin's import.meta.url (used to locate generated JSON)
+ * @param name — Display name (e.g. "AWS Resource Catalog")
+ * @param description — Resource description
+ * @param lexiconJsonFile — Filename of the generated lexicon JSON (e.g. "lexicon-aws.json")
+ * @param lexiconName — Short lexicon name (e.g. "aws", "gcp"). Becomes the URI prefix.
+ */
+export function createCatalogResource(importMetaUrl, name, description, lexiconJsonFile, lexiconName) {
+    return {
+        uri: `${lexiconName}:resource-catalog`,
+        name,
+        description,
+        mimeType: "application/json",
+        async handler() {
+            const dir = dirname(fileURLToPath(importMetaUrl));
+            const lexicon = JSON.parse(readFileSync(join(dir, "generated", lexiconJsonFile), "utf-8"));
+            const entries = Object.entries(lexicon).map(([className, entry]) => ({
+                className,
+                resourceType: entry.resourceType,
+                kind: entry.kind,
+            }));
+            return JSON.stringify(entries);
+        },
+    };
+}