@intentius/chant 0.124.13 → 0.124.14

package/dist/lint/rules/evl007-invalid-siblings.js

@@ -0,0 +1,105 @@
+import * as ts from "typescript";
+/**
+ * EVL007: Invalid Siblings Access
+ *
+ * In a Composite factory, resource() callbacks receive a `siblings` parameter.
+ * Accessing siblings.key must reference a key that exists in the composite's
+ * resource map.
+ */
+function checkNode(node, context, diagnostics) {
+    // Look for Composite(...) calls
+    if (ts.isCallExpression(node) &&
+        ts.isIdentifier(node.expression) &&
+        node.expression.text === "Composite") {
+        // The factory function is the argument to Composite
+        const factoryArg = node.arguments[0];
+        if (factoryArg && (ts.isArrowFunction(factoryArg) || ts.isFunctionExpression(factoryArg))) {
+            checkCompositeFactory(factoryArg, context, diagnostics);
+        }
+    }
+    ts.forEachChild(node, (child) => checkNode(child, context, diagnostics));
+}
+function checkCompositeFactory(factory, context, diagnostics) {
+    // The factory body should contain an object literal with resource() calls
+    // that define the composite members. Collect the keys.
+    const body = factory.body;
+    let memberKeys = null;
+    if (ts.isBlock(body)) {
+        // Look for return statement with object literal
+        for (const stmt of body.statements) {
+            if (ts.isReturnStatement(stmt) && stmt.expression && ts.isObjectLiteralExpression(stmt.expression)) {
+                memberKeys = collectObjectKeys(stmt.expression);
+            }
+        }
+    }
+    else if (ts.isParenthesizedExpression(body) && ts.isObjectLiteralExpression(body.expression)) {
+        memberKeys = collectObjectKeys(body.expression);
+    }
+    else if (ts.isObjectLiteralExpression(body)) {
+        memberKeys = collectObjectKeys(body);
+    }
+    if (!memberKeys || memberKeys.size === 0)
+        return;
+    // Now find resource() calls within the factory and check siblings access
+    walkForResourceCalls(body, memberKeys, context, diagnostics);
+}
+function collectObjectKeys(obj) {
+    const keys = new Set();
+    for (const prop of obj.properties) {
+        if (ts.isPropertyAssignment(prop) || ts.isShorthandPropertyAssignment(prop)) {
+            if (ts.isIdentifier(prop.name)) {
+                keys.add(prop.name.text);
+            }
+            else if (ts.isStringLiteral(prop.name)) {
+                keys.add(prop.name.text);
+            }
+        }
+    }
+    return keys;
+}
+function walkForResourceCalls(node, memberKeys, context, diagnostics) {
+    if (ts.isCallExpression(node) &&
+        ts.isIdentifier(node.expression) &&
+        node.expression.text === "resource") {
+        // resource(Type, (props, siblings) => ...)
+        const callback = node.arguments[1];
+        if (callback && (ts.isArrowFunction(callback) || ts.isFunctionExpression(callback))) {
+            const siblingsParam = callback.parameters[1];
+            if (siblingsParam && ts.isIdentifier(siblingsParam.name)) {
+                const siblingsName = siblingsParam.name.text;
+                checkSiblingsAccess(callback.body, siblingsName, memberKeys, context, diagnostics);
+            }
+        }
+    }
+    ts.forEachChild(node, (child) => walkForResourceCalls(child, memberKeys, context, diagnostics));
+}
+function checkSiblingsAccess(node, siblingsName, memberKeys, context, diagnostics) {
+    if (ts.isPropertyAccessExpression(node)) {
+        if (ts.isIdentifier(node.expression) && node.expression.text === siblingsName) {
+            const accessedKey = node.name.text;
+            if (!memberKeys.has(accessedKey)) {
+                const { line, character } = context.sourceFile.getLineAndCharacterOfPosition(node.getStart(context.sourceFile));
+                diagnostics.push({
+                    file: context.filePath,
+                    line: line + 1,
+                    column: character + 1,
+                    ruleId: "EVL007",
+                    severity: "error",
+                    message: `Invalid siblings access — "${accessedKey}" is not a member of this composite`,
+                });
+            }
+        }
+    }
+    ts.forEachChild(node, (child) => checkSiblingsAccess(child, siblingsName, memberKeys, context, diagnostics));
+}
+export const evl007InvalidSiblingsRule = {
+    id: "EVL007",
+    severity: "error",
+    category: "correctness",
+    description: "Validates that siblings access in Composite factories references existing member keys",
+    check(context) {
+        const diagnostics = [];
+        checkNode(context.sourceFile, context, diagnostics);
+        return diagnostics;
+    },
+};

package/dist/lint/rules/evl009-composite-no-constant.js

@@ -0,0 +1,158 @@
+import * as ts from "typescript";
+import { getCompositeFactory } from "./composite-scope.js";
+/**
+ * EVL009: No extractable constants inside Composite factory
+ *
+ * Composite factories should only reference props, sibling members, and
+ * imported identifiers. Object literals and arrays-of-objects that don't
+ * reference any of these are extractable constants that belong in a
+ * separate file (e.g. defaults.ts).
+ *
+ * Triggers on: assumeRolePolicyDocument: { Version: "2012-10-17", Statement: [...] }
+ * Triggers on: managedPolicyArns: ["arn:aws:iam::aws:policy/..."]
+ * OK: assumeRolePolicyDocument: lambdaTrustPolicy (imported)
+ * OK: policies: props.policies
+ * OK: role: role.arn
+ * OK: action: "lambda:InvokeFunction" (simple string literal — not an object)
+ */
+/**
+ * Collect all imported identifiers from import declarations in the file.
+ */
+function collectImportedNames(sourceFile) {
+    const names = new Set();
+    for (const stmt of sourceFile.statements) {
+        if (!ts.isImportDeclaration(stmt) || !stmt.importClause)
+            continue;
+        // import foo from "..."
+        if (stmt.importClause.name) {
+            names.add(stmt.importClause.name.text);
+        }
+        const bindings = stmt.importClause.namedBindings;
+        if (!bindings)
+            continue;
+        if (ts.isNamespaceImport(bindings)) {
+            // import * as ns from "..."
+            names.add(bindings.name.text);
+        }
+        else if (ts.isNamedImports(bindings)) {
+            // import { a, b } from "..."
+            for (const spec of bindings.elements) {
+                names.add(spec.name.text);
+            }
+        }
+    }
+    return names;
+}
+/**
+ * Check whether any leaf node in the subtree references:
+ * - The props parameter identifier
+ * - An imported identifier (direct import or namespace import)
+ * - A local variable declared in the composite factory body
+ */
+function referencesPropsOrMembers(node, propsName, localNames, importedNames) {
+    if (ts.isIdentifier(node)) {
+        // Direct props reference
+        if (node.text === propsName)
+            return true;
+        // Local variable reference (sibling member)
+        if (localNames.has(node.text))
+            return true;
+        // Imported identifier (direct or namespace)
+        if (importedNames.has(node.text))
+            return true;
+    }
+    let found = false;
+    ts.forEachChild(node, (child) => {
+        if (!found && referencesPropsOrMembers(child, propsName, localNames, importedNames)) {
+            found = true;
+        }
+    });
+    return found;
+}
+/**
+ * Check if a value is an extractable constant:
+ * - Object literal (with any nesting)
+ * - Array literal containing object literals
+ * Simple primitives (string, number, boolean) are allowed inline.
+ */
+function isExtractableShape(node) {
+    if (ts.isObjectLiteralExpression(node))
+        return true;
+    if (ts.isArrayLiteralExpression(node)) {
+        return node.elements.some((el) => ts.isObjectLiteralExpression(el) || ts.isArrayLiteralExpression(el));
+    }
+    return false;
+}
+function checkComposite(call, context, diagnostics, importedNames) {
+    const factory = call.arguments[0];
+    if (!factory || (!ts.isArrowFunction(factory) && !ts.isFunctionExpression(factory)))
+        return;
+    // Get props parameter name
+    const propsParam = factory.parameters[0];
+    const propsName = propsParam && ts.isIdentifier(propsParam.name) ? propsParam.name.text : "";
+    // Collect local variable names declared in the factory body
+    const localNames = new Set();
+    const body = factory.body;
+    if (ts.isBlock(body)) {
+        for (const stmt of body.statements) {
+            if (ts.isVariableStatement(stmt)) {
+                for (const decl of stmt.declarationList.declarations) {
+                    if (ts.isIdentifier(decl.name)) {
+                        localNames.add(decl.name.text);
+                    }
+                }
+            }
+        }
+    }
+    // Walk all NewExpression nodes inside the factory body
+    checkForConstants(body, context, diagnostics, propsName, localNames, importedNames);
+}
+function checkForConstants(node, context, diagnostics, propsName, localNames, importedNames) {
+    if (ts.isNewExpression(node) && node.arguments && node.arguments.length > 0) {
+        const firstArg = node.arguments[0];
+        if (ts.isObjectLiteralExpression(firstArg)) {
+            for (const prop of firstArg.properties) {
+                if (!ts.isPropertyAssignment(prop))
+                    continue;
+                const value = prop.initializer;
+                if (isExtractableShape(value) && !referencesPropsOrMembers(value, propsName, localNames, importedNames)) {
+                    const propName = ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name)
+                        ? (ts.isIdentifier(prop.name) ? prop.name.text : prop.name.text)
+                        : "<computed>";
+                    const { line, character } = context.sourceFile.getLineAndCharacterOfPosition(value.getStart(context.sourceFile));
+                    diagnostics.push({
+                        file: context.filePath,
+                        line: line + 1,
+                        column: character + 1,
+                        ruleId: "EVL009",
+                        severity: "warning",
+                        message: `Extractable constant in Composite factory property "${propName}" — move to a separate file and import directly`,
+                    });
+                }
+            }
+        }
+    }
+    ts.forEachChild(node, (child) => checkForConstants(child, context, diagnostics, propsName, localNames, importedNames));
+}
+function checkNode(node, context, diagnostics, importedNames) {
+    if (ts.isCallExpression(node)) {
+        const factory = getCompositeFactory(node);
+        if (factory) {
+            checkComposite(node, context, diagnostics, importedNames);
+            return; // Don't recurse further — checkComposite handles it
+        }
+    }
+    ts.forEachChild(node, (child) => checkNode(child, context, diagnostics, importedNames));
+}
+export const evl009CompositeNoConstantRule = {
+    id: "EVL009",
+    severity: "warning",
+    category: "style",
+    description: "Flags extractable constants inside Composite factories — move to a separate file",
+    check(context) {
+        const diagnostics = [];
+        const importedNames = collectImportedNames(context.sourceFile);
+        checkNode(context.sourceFile, context, diagnostics, importedNames);
+        return diagnostics;
+    },
+};

package/dist/lint/rules/evl010-composite-no-transform.js

@@ -0,0 +1,59 @@
+import * as ts from "typescript";
+import { isInsideCompositeFactory } from "./composite-scope.js";
+/**
+ * EVL010: No data transformation inside Composite factory
+ *
+ * Composite factories should only compose resources from props, not transform data.
+ * Data transformation (map, filter, reduce, etc.) should happen before passing props.
+ *
+ * Triggers on: props.items.map(x => new Thing(x))
+ * Triggers on: props.list.filter(Boolean)
+ * Triggers on: Object.keys(props.env).reduce(...)
+ * OK: props.policies (pass-through)
+ * OK: [a, b] (array literal)
+ */
+const TRANSFORM_METHODS = new Set([
+    "map",
+    "filter",
+    "reduce",
+    "flatMap",
+    "forEach",
+    "find",
+    "some",
+    "every",
+    "sort",
+    "reverse",
+    "splice",
+    "slice",
+    "concat",
+]);
+function checkNode(node, context, diagnostics) {
+    if (ts.isCallExpression(node) &&
+        ts.isPropertyAccessExpression(node.expression) &&
+        isInsideCompositeFactory(node)) {
+        const methodName = node.expression.name.text;
+        if (TRANSFORM_METHODS.has(methodName)) {
+            const { line, character } = context.sourceFile.getLineAndCharacterOfPosition(node.expression.name.getStart(context.sourceFile));
+            diagnostics.push({
+                file: context.filePath,
+                line: line + 1,
+                column: character + 1,
+                ruleId: "EVL010",
+                severity: "warning",
+                message: `Data transformation .${methodName}() inside Composite factory — transform data before passing it as props`,
+            });
+        }
+    }
+    ts.forEachChild(node, (child) => checkNode(child, context, diagnostics));
+}
+export const evl010CompositeNoTransformRule = {
+    id: "EVL010",
+    severity: "warning",
+    category: "style",
+    description: "Flags data transformations (map, filter, reduce) inside Composite factories",
+    check(context) {
+        const diagnostics = [];
+        checkNode(context.sourceFile, context, diagnostics);
+        return diagnostics;
+    },
+};

package/dist/lint/rules/evl011-symbolic-in-template.js

@@ -0,0 +1,106 @@
+import * as ts from "typescript";
+/**
+ * EVL011: a symbolic reference inside a plain template literal
+ *
+ * `` `${bucket.arn}-suffix` `` cannot be evaluated to a string. A resource
+ * attribute stands for a value the build resolves later, so there is nothing
+ * to interpolate yet, and JavaScript's answer — `"[object Object]"` — is
+ * wrong on both of chant's paths.
+ *
+ * This rule is the friendly half of #2349. The unfriendly half already landed:
+ * `fold()` refuses the span with a located error and `AttrRef.toString` throws,
+ * so the program fails either way. What a rule adds is finding it at lint time
+ * with the remedy attached, rather than at build time with a stack.
+ *
+ * ## Why it is a heuristic, and why that is acceptable here
+ *
+ * Lint sees syntax, not values. `foo.bar` inside a template is a resource
+ * attribute only if `foo` is a resource, which is a fact `fold()` has and this
+ * rule does not — so the check is: a property access whose object is a
+ * plain identifier bound in this file by `new`. That is the shape #2349 was
+ * reported against and the shape a lexicon's own docs show.
+ *
+ * It therefore misses a reference reached some other way (through a parameter,
+ * an array, a helper's return) and does not flag an access on a plain object.
+ * Missing a case costs nothing, because `fold()` still refuses it; flagging a
+ * plain object would be a false positive on code that works, which is the
+ * error worth avoiding. This is the same asymmetry `../../fold/subset.ts`
+ * documents for EVL generally, pointed the other way: there EVL may be
+ * stricter than fold, here it is deliberately looser.
+ */
+/** Identifiers bound by `const x = new T(...)` at any depth in this file. */
+function resourceBindings(sourceFile) {
+    const names = new Set();
+    const visit = (node) => {
+        if (ts.isVariableDeclaration(node) &&
+            ts.isIdentifier(node.name) &&
+            node.initializer &&
+            ts.isNewExpression(node.initializer)) {
+            names.add(node.name.text);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return names;
+}
+/**
+ * What this span is, if it is one of the shapes that has no string form — or
+ * `undefined` for an ordinary expression.
+ *
+ * The three kinds a syntactic rule can see, matching what `fold()` refuses
+ * (#2397): a resource attribute on an identifier bound by `new` in this file,
+ * a nested construction used as a value, and a composite `.step`.
+ */
+function symbolicSpan(expr, bound) {
+    if (ts.isNewExpression(expr)) {
+        const name = ts.isIdentifier(expr.expression) ? expr.expression.text : "…";
+        return `a nested \`new ${name}\``;
+    }
+    if (ts.isPropertyAccessExpression(expr)) {
+        // `Checkout({}).step` — a call's `.step`, whatever the callee is: the
+        // idiom is the shape, and a rule cannot know which callees are composites.
+        if (expr.name.text === "step" && ts.isCallExpression(expr.expression)) {
+            const callee = ts.isIdentifier(expr.expression.expression) ? expr.expression.expression.text : "…";
+            return `the composite step \`${callee}(…).step\``;
+        }
+        if (ts.isIdentifier(expr.expression) && bound.has(expr.expression.text)) {
+            return `\`${expr.expression.text}.${expr.name.text}\` is a resource attribute and`;
+        }
+    }
+    return undefined;
+}
+function checkNode(node, context, bound, diagnostics) {
+    // Untagged only: a tagged template is the documented remedy, and its
+    // interior handles envelopes.
+    if (ts.isTemplateExpression(node) && !ts.isTaggedTemplateExpression(node.parent)) {
+        for (const span of node.templateSpans) {
+            const expr = span.expression;
+            const what = symbolicSpan(expr, bound);
+            if (what) {
+                const { line, character } = context.sourceFile.getLineAndCharacterOfPosition(expr.getStart(context.sourceFile));
+                diagnostics.push({
+                    file: context.filePath,
+                    line: line + 1,
+                    column: character + 1,
+                    ruleId: "EVL011",
+                    severity: "error",
+                    message: `${what} has no string form until the build resolves it — a plain template would ` +
+                        "stringify it as \"[object Object]\". Use the lexicon's own intrinsic, whose interior " +
+                        "handles these (`Sub`${…}`` for CloudFormation), or move it out of the template.",
+                });
+            }
+        }
+    }
+    ts.forEachChild(node, (child) => checkNode(child, context, bound, diagnostics));
+}
+export const evl011SymbolicInTemplateRule = {
+    id: "EVL011",
+    severity: "error",
+    category: "correctness",
+    description: "A resource attribute cannot be interpolated into a plain template literal",
+    check(context) {
+        const diagnostics = [];
+        checkNode(context.sourceFile, context, resourceBindings(context.sourceFile), diagnostics);
+        return diagnostics;
+    },
+};

package/dist/lint/rules/export-required.js

@@ -0,0 +1,115 @@
+import * as ts from "typescript";
+function isDeclarableClass(node, sourceFile) {
+    // Check if it's a class with Declarable interface implementation
+    if (ts.isClassDeclaration(node) && node.heritageClauses) {
+        for (const clause of node.heritageClauses) {
+            for (const type of clause.types) {
+                const typeName = type.expression.getText(sourceFile);
+                if (typeName === "Declarable") {
+                    return true;
+                }
+            }
+        }
+    }
+    return false;
+}
+function collectExportInfo(sourceFile) {
+    const exportedNames = new Set();
+    const localVariableNames = new Set();
+    function visit(node) {
+        // Handle exported variable declarations
+        if (ts.isVariableStatement(node)) {
+            const hasExportModifier = node.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword);
+            for (const declaration of node.declarationList.declarations) {
+                if (ts.isIdentifier(declaration.name)) {
+                    const name = declaration.name.text;
+                    if (hasExportModifier) {
+                        exportedNames.add(name);
+                    }
+                    else {
+                        localVariableNames.add(name);
+                    }
+                }
+            }
+        }
+        // Handle export assignments: export = something
+        if (ts.isExportAssignment(node)) {
+            if (ts.isIdentifier(node.expression)) {
+                exportedNames.add(node.expression.text);
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return { exportedNames, localVariableNames };
+}
+function isDeclarableNewExpression(node, context) {
+    // Check if the class being instantiated implements Declarable
+    // We look for the class declaration in the source file or imports
+    const className = node.expression.getText(context.sourceFile);
+    // Check local class declarations
+    let isDeclarable = false;
+    function checkClassDeclarations(n) {
+        if (ts.isClassDeclaration(n) && n.name?.text === className) {
+            if (isDeclarableClass(n, context.sourceFile)) {
+                isDeclarable = true;
+            }
+        }
+        ts.forEachChild(n, checkClassDeclarations);
+    }
+    checkClassDeclarations(context.sourceFile);
+    // For imported classes, we use a heuristic: check if the class name is capitalized
+    // and follows common declarable patterns (like Bucket, Parameter, etc.)
+    if (!isDeclarable && /^[A-Z]/.test(className)) {
+        // Additional check: see if it's imported from a declarable-looking module
+        // For now, we'll be conservative and only flag classes that are clearly local
+        return isDeclarable;
+    }
+    return isDeclarable;
+}
+function checkNode(node, context, exportInfo, diagnostics) {
+    // Check for new expressions that are not exported
+    if (ts.isNewExpression(node)) {
+        // Skip if this is part of a variable initializer that's exported
+        let parent = node.parent;
+        let isPartOfExportedVariable = false;
+        let variableName;
+        while (parent) {
+            if (ts.isVariableDeclaration(parent) && ts.isIdentifier(parent.name)) {
+                variableName = parent.name.text;
+                if (exportInfo.exportedNames.has(variableName)) {
+                    isPartOfExportedVariable = true;
+                    break;
+                }
+            }
+            parent = parent.parent;
+        }
+        if (!isPartOfExportedVariable && isDeclarableNewExpression(node, context)) {
+            const { line, character } = context.sourceFile.getLineAndCharacterOfPosition(node.getStart(context.sourceFile));
+            const className = node.expression.getText(context.sourceFile);
+            const label = variableName ? `'${variableName}' (${className})` : `'${className}'`;
+            diagnostics.push({
+                file: context.filePath,
+                line: line + 1,
+                column: character + 1,
+                ruleId: "COR008",
+                severity: "warning",
+                message: `Declarable ${label} is not exported — add 'export' so chant can discover it during synthesis.`,
+            });
+        }
+    }
+    // Recursively check child nodes
+    ts.forEachChild(node, child => checkNode(child, context, exportInfo, diagnostics));
+}
+export const exportRequiredRule = {
+    id: "COR008",
+    severity: "warning",
+    category: "correctness",
+    description: "Detects declarable instances that are not exported for chant discovery",
+    check(context) {
+        const diagnostics = [];
+        const exportInfo = collectExportInfo(context.sourceFile);
+        checkNode(context.sourceFile, context, exportInfo, diagnostics);
+        return diagnostics;
+    },
+};

package/dist/lint/rules/file-declarable-limit.js

@@ -0,0 +1,88 @@
+import * as ts from "typescript";
+import { isPropertyKindNew } from "./property-kind.js";
+const DECLARABLE_LIMIT = 8;
+const BUILTIN_CONSTRUCTORS = new Set([
+    "Array",
+    "ArrayBuffer",
+    "BigInt64Array",
+    "BigUint64Array",
+    "Boolean",
+    "DataView",
+    "Date",
+    "Error",
+    "EvalError",
+    "Float32Array",
+    "Float64Array",
+    "Int8Array",
+    "Int16Array",
+    "Int32Array",
+    "Map",
+    "Number",
+    "Object",
+    "Promise",
+    "Proxy",
+    "RangeError",
+    "ReferenceError",
+    "RegExp",
+    "Set",
+    "SharedArrayBuffer",
+    "String",
+    "SyntaxError",
+    "TypeError",
+    "URIError",
+    "URL",
+    "URLSearchParams",
+    "Uint8Array",
+    "Uint8ClampedArray",
+    "Uint16Array",
+    "Uint32Array",
+    "WeakMap",
+    "WeakRef",
+    "WeakSet",
+]);
+function isDeclarableConstructor(node) {
+    const expr = node.expression;
+    if (ts.isIdentifier(expr)) {
+        const name = expr.text;
+        return (name.length > 0 &&
+            name[0] >= "A" &&
+            name[0] <= "Z" &&
+            !BUILTIN_CONSTRUCTORS.has(name));
+    }
+    return false;
+}
+/**
+ * Collect the declarable `new` expressions this rule counts. Property-kind
+ * declarables (chant #2957) are left out: a dashboard with twenty panels,
+ * queries and variables is one resource, not twenty-one.
+ */
+function collectDeclarableNewExpressions(node, context, results) {
+    if (ts.isNewExpression(node) && isDeclarableConstructor(node) && !isPropertyKindNew(node, context)) {
+        results.push(node);
+    }
+    ts.forEachChild(node, (child) => collectDeclarableNewExpressions(child, context, results));
+}
+export const fileDeclarableLimitRule = {
+    id: "COR009",
+    severity: "warning",
+    category: "style",
+    description: "Limits the number of resource Declarable instances per file to encourage splitting by concern; property-kind declarables are not counted",
+    check(context, options) {
+        const limit = (typeof options?.max === "number" ? options.max : null) ?? DECLARABLE_LIMIT;
+        const instances = [];
+        collectDeclarableNewExpressions(context.sourceFile, context, instances);
+        if (instances.length > limit) {
+            return [
+                {
+                    file: context.filePath,
+                    line: 1,
+                    column: 1,
+                    ruleId: "COR009",
+                    severity: "warning",
+                    message: `File contains ${instances.length} Declarable instances (limit: ${limit}) — consider splitting into separate files by concern`,
+                },
+            ];
+        }
+        return [];
+    },
+};