@intentius/chant 0.124.13 → 0.124.15

package/dist/lint/rules/cor024-receipt-secret-pointer.js

@@ -0,0 +1,199 @@
+import * as ts from "typescript";
+import { receiptFactoryCall } from "./cor022-receipt-leaf.js";
+/**
+ * COR024: Receipt Inputs Reference Secrets by Pointer (#1833, epic #1703;
+ * composes with the secret-provenance work, #1365/#1828)
+ *
+ * A receipt's `inputs` feed its expectation hash (../../effect-receipt.ts) —
+ * whatever lands there is canonicalized, digested, and compared against a
+ * stored value for the rest of the receipt's life. chant's constitutional
+ * line on secrets is that no code path may hold, log, hash, or compare a
+ * secret value (../../secret-provenance.ts), so a receipt input that reads a
+ * Secret-kind entity's material (`.data`, `.value`, `.stringData`, ...)
+ * violates it twice over: the material enters the hash, and the serialized
+ * placeholder ties the receipt to the secret's value rather than its
+ * identity.
+ *
+ * The pointer form is fine — and is the point: reference the secret by name
+ * and version (`{ secretName: dbSecret.name, secretVersion: 3 }`), so a
+ * rotation is an explicit version bump that re-proposes the effect, and the
+ * hash only ever sees the pointer.
+ *
+ * Recognition is the same file-local reference walk COR022 uses (const
+ * indirection included): a variable is Secret-kind when its initializer is a
+ * constructor or factory whose name says so (`new SecretManagerSecret(...)`,
+ * `new ExternalSecret(...)`, `declareSecret(...)`); an input fires when a
+ * property chain rooted at one of those crosses a material field.
+ */
+/** Fields that carry secret material. Mirrors secret-provenance.ts's
+ * FORBIDDEN_MATERIAL_FIELDS, plus the provider-attribute spellings
+ * (`secretString`/`secretValue`) a materialized secret exposes. */
+const MATERIAL_FIELDS = new Set([
+    "value",
+    "data",
+    "stringdata",
+    "material",
+    "plaintext",
+    "ciphertext",
+    "secretstring",
+    "secretvalue",
+]);
+function isMaterialField(name) {
+    return MATERIAL_FIELDS.has(name.toLowerCase());
+}
+/** Simple name of a `new X(...)` / `X(...)` / `ns.X(...)` initializer. */
+function initializerName(init) {
+    if (!ts.isNewExpression(init) && !ts.isCallExpression(init))
+        return undefined;
+    const callee = init.expression;
+    if (ts.isIdentifier(callee))
+        return callee.text;
+    if (ts.isPropertyAccessExpression(callee))
+        return callee.name.text;
+    return undefined;
+}
+/** Does this constructor/factory name declare a Secret-kind entity? */
+function isSecretKindName(name) {
+    return /secret/i.test(name) || name === "declareSecret";
+}
+/** One access chain: `sec.data.password` → root "sec", segments ["data","password"]. */
+function decomposeChain(node) {
+    const segments = [];
+    let current = node;
+    while (ts.isPropertyAccessExpression(current) || ts.isElementAccessExpression(current)) {
+        if (ts.isPropertyAccessExpression(current)) {
+            segments.unshift(current.name.text);
+        }
+        else {
+            const arg = current.argumentExpression;
+            segments.unshift(ts.isStringLiteralLike(arg) ? arg.text : "<computed>");
+        }
+        current = current.expression;
+    }
+    if (!ts.isIdentifier(current))
+        return undefined;
+    return { root: current.text, segments };
+}
+/** File-local Secret-kind variables, aliases and material extractions, to a fixpoint. */
+function collectSecretVariables(sourceFile) {
+    const secretRooted = new Set();
+    const material = new Set();
+    const derived = [];
+    function visit(node) {
+        if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) {
+            const init = node.initializer;
+            const ctorName = initializerName(init);
+            if (ctorName !== undefined && isSecretKindName(ctorName)) {
+                secretRooted.add(node.name.text);
+            }
+            else if (ts.isIdentifier(init)) {
+                derived.push({ name: node.name.text, root: init.text, crossesMaterial: false, isBareAlias: true });
+            }
+            else if (ts.isPropertyAccessExpression(init) || ts.isElementAccessExpression(init)) {
+                const chain = decomposeChain(init);
+                if (chain) {
+                    derived.push({
+                        name: node.name.text,
+                        root: chain.root,
+                        crossesMaterial: chain.segments.some(isMaterialField),
+                        isBareAlias: false,
+                    });
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    let grew = true;
+    while (grew) {
+        grew = false;
+        for (const d of derived) {
+            const rootIsSecret = secretRooted.has(d.root);
+            const rootIsMaterial = material.has(d.root);
+            if (!rootIsSecret && !rootIsMaterial)
+                continue;
+            const target = rootIsMaterial || d.crossesMaterial ? material : secretRooted;
+            if (d.isBareAlias && !d.crossesMaterial && rootIsSecret) {
+                if (!secretRooted.has(d.name)) {
+                    secretRooted.add(d.name);
+                    grew = true;
+                }
+            }
+            else if (!target.has(d.name)) {
+                target.add(d.name);
+                grew = true;
+            }
+        }
+    }
+    return { secretRooted, material };
+}
+export const cor024ReceiptSecretPointerRule = {
+    id: "COR024",
+    severity: "error",
+    category: "correctness",
+    description: "A receipt's inputs may reference a secret only by name+version pointer, never by value — secret material must not enter the expectation hash",
+    check(context) {
+        const diagnostics = [];
+        const secrets = collectSecretVariables(context.sourceFile);
+        if (secrets.secretRooted.size === 0 && secrets.material.size === 0)
+            return diagnostics;
+        const report = (node, rendered, root) => {
+            const { line, character } = context.sourceFile.getLineAndCharacterOfPosition(node.getStart(context.sourceFile));
+            diagnostics.push({
+                file: context.filePath,
+                line: line + 1,
+                column: character + 1,
+                ruleId: "COR024",
+                severity: "error",
+                message: `Receipt input reads secret material (${rendered}) from "${root}" — a receipt's inputs may ` +
+                    `reference a secret only by name+version pointer, never by value: the inputs are hashed into ` +
+                    `the receipt's expectation, and no chant code path may hash or compare secret material. ` +
+                    `Use the pointer form instead, e.g. { secretName: ${root}.name, secretVersion: 3 } — ` +
+                    `a rotation then re-proposes the effect through an explicit version bump.`,
+            });
+        };
+        const checkInputs = (inputs) => {
+            const visit = (node) => {
+                if (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) {
+                    const chain = decomposeChain(node);
+                    if (chain) {
+                        const rootMaterial = secrets.material.has(chain.root);
+                        const crossesMaterial = chain.segments.some(isMaterialField);
+                        if (rootMaterial || (secrets.secretRooted.has(chain.root) && crossesMaterial)) {
+                            report(node, `\`${chain.root}.${chain.segments.join(".")}\``, chain.root);
+                            return; // one diagnostic per chain, not one per link
+                        }
+                    }
+                }
+                else if (ts.isIdentifier(node) && secrets.material.has(node.text)) {
+                    const parent = node.parent;
+                    const isChainBase = (ts.isPropertyAccessExpression(parent) || ts.isElementAccessExpression(parent)) &&
+                        parent.expression === node;
+                    const isKey = ts.isPropertyAssignment(parent) && parent.name === node;
+                    if (!isChainBase && !isKey)
+                        report(node, `\`${node.text}\``, node.text);
+                }
+                ts.forEachChild(node, visit);
+            };
+            visit(inputs);
+        };
+        const walk = (node) => {
+            if (ts.isVariableDeclaration(node)) {
+                const call = receiptFactoryCall(node);
+                const options = call?.arguments[1];
+                if (options && ts.isObjectLiteralExpression(options)) {
+                    for (const prop of options.properties) {
+                        if (ts.isPropertyAssignment(prop) &&
+                            (ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name)) &&
+                            prop.name.text === "inputs") {
+                            checkInputs(prop.initializer);
+                        }
+                    }
+                }
+            }
+            ts.forEachChild(node, walk);
+        };
+        walk(context.sourceFile);
+        return diagnostics;
+    },
+};

package/dist/lint/rules/declarable-naming-convention.js

@@ -0,0 +1,62 @@
+import * as ts from "typescript";
+/**
+ * COR005: declarable-naming-convention
+ *
+ * Exported declarable instances (i.e. `export const x = new SomeClass(...)`)
+ * must use camelCase names. Flags PascalCase and UPPER_SNAKE_CASE names.
+ *
+ * Triggers on: export const DataBucket = new Bucket({ ... })
+ * Triggers on: export const DATA_BUCKET = new Bucket({ ... })
+ * OK: export const dataBucket = new Bucket({ ... })
+ * OK: export const DataBucket = createBucket({ ... })  (not a new expression)
+ * OK: const DataBucket = new Bucket({ ... })  (not exported)
+ */
+function checkNode(node, context, diagnostics) {
+    if (ts.isVariableStatement(node)) {
+        const hasExport = node.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword);
+        if (!hasExport) {
+            ts.forEachChild(node, child => checkNode(child, context, diagnostics));
+            return;
+        }
+        for (const decl of node.declarationList.declarations) {
+            if (!ts.isIdentifier(decl.name))
+                continue;
+            if (!decl.initializer || !ts.isNewExpression(decl.initializer))
+                continue;
+            const name = decl.name.text;
+            // camelCase starts with lowercase — that's fine
+            if (/^[a-z]/.test(name))
+                continue;
+            const { line, character } = context.sourceFile.getLineAndCharacterOfPosition(decl.name.getStart(context.sourceFile));
+            diagnostics.push({
+                file: context.filePath,
+                line: line + 1,
+                column: character + 1,
+                ruleId: "COR005",
+                severity: "warning",
+                message: `Declarable '${name}' should use camelCase naming — rename to '${toCamelCase(name)}'.`,
+            });
+        }
+    }
+    ts.forEachChild(node, child => checkNode(child, context, diagnostics));
+}
+/** Suggest a camelCase version of a PascalCase or UPPER_SNAKE_CASE name */
+function toCamelCase(name) {
+    // PascalCase -> camelCase: lowercase first char
+    if (/^[A-Z][a-z]/.test(name)) {
+        return name[0].toLowerCase() + name.slice(1);
+    }
+    // UPPER_SNAKE -> camelCase
+    return name.toLowerCase().replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}
+export const declarableNamingConventionRule = {
+    id: "COR005",
+    severity: "warning",
+    category: "style",
+    description: "Exported declarable instances must use camelCase naming",
+    check(context) {
+        const diagnostics = [];
+        checkNode(context.sourceFile, context, diagnostics);
+        return diagnostics;
+    },
+};

package/dist/lint/rules/evl001-non-literal-expression.js

@@ -0,0 +1,66 @@
+import * as ts from "typescript";
+import { isInsideCompositeFactory } from "./composite-scope.js";
+import { checkObjectMember } from "../../fold/subset.js";
+/**
+ * EVL001: Non-Literal Expression in Resource Constructor
+ *
+ * Resource constructor property values must be statically evaluable.
+ * Allowed: literals, identifiers, property access, object/array literals,
+ * template expressions, binary/unary/conditional, as/satisfies casts.
+ * Blocked: function calls, method calls, and other dynamic expressions.
+ *
+ * This is a *diagnostic* (chant #1024, epic #1019) — it exists to give a
+ * friendly, early, precisely-located error before synthesis, over exactly
+ * the same subset definition `fold()` (the actual enforcement layer,
+ * {@link "../../fold/fold"}) uses to decide what it can reduce. Both import
+ * the single classifier in {@link "../../fold/subset"}
+ * ({@link checkObjectMember}) so a construct flagged here is exactly a
+ * construct `fold()` rejects, and vice versa — see that module's doc
+ * comment for the few environment-dependent exceptions (identifier
+ * resolution, intrinsic tag registration, spread-source runtime type,
+ * `&&`/`||`/`??`/`? :` short-circuit laziness) that can't be unified
+ * through shape alone.
+ */
+function checkNode(node, context, diagnostics) {
+    // Skip resource constructors inside Composite() factory callbacks
+    if (ts.isNewExpression(node) && !isInsideCompositeFactory(node)) {
+        if (node.arguments && node.arguments.length > 0) {
+            const firstArg = node.arguments[0];
+            if (ts.isObjectLiteralExpression(firstArg)) {
+                for (const prop of firstArg.properties) {
+                    // `Checkout({...}).step` — the single-action Composite()-wrapper
+                    // idiom every lexicon's own docs/examples embed inline inside a
+                    // Job's `steps:` array — is shape-valid unconditionally (chant
+                    // #1544 introduced this as an EVL-only opt-in while `fold()`
+                    // still rejected the shape; chant #1174 closed that divergence by
+                    // making `fold()` accept it too, so `findSubsetViolation` no
+                    // longer needs a flag to say so).
+                    const violation = checkObjectMember(prop, context.intrinsics);
+                    if (violation) {
+                        const { line, character } = context.sourceFile.getLineAndCharacterOfPosition(violation.node.getStart(context.sourceFile));
+                        diagnostics.push({
+                            file: context.filePath,
+                            line: line + 1,
+                            column: character + 1,
+                            ruleId: "EVL001",
+                            severity: "error",
+                            message: `Non-literal expression in resource constructor property — value must be statically evaluable`,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    ts.forEachChild(node, (child) => checkNode(child, context, diagnostics));
+}
+export const evl001NonLiteralExpressionRule = {
+    id: "EVL001",
+    severity: "error",
+    category: "correctness",
+    description: "Resource constructor property values must be statically evaluable — no function calls",
+    check(context) {
+        const diagnostics = [];
+        checkNode(context.sourceFile, context, diagnostics);
+        return diagnostics;
+    },
+};

package/dist/lint/rules/evl002-control-flow-resource.js

@@ -0,0 +1,69 @@
+import * as ts from "typescript";
+/**
+ * EVL002: Control Flow Wrapping Resources
+ *
+ * Resource constructors (NewExpression) must not appear inside
+ * control flow statements (if, for, while, switch, try, etc.).
+ * Resources must be unconditionally declared.
+ */
+const CONTROL_FLOW_KINDS = new Set([
+    ts.SyntaxKind.IfStatement,
+    ts.SyntaxKind.ForStatement,
+    ts.SyntaxKind.ForInStatement,
+    ts.SyntaxKind.ForOfStatement,
+    ts.SyntaxKind.WhileStatement,
+    ts.SyntaxKind.DoStatement,
+    ts.SyntaxKind.SwitchStatement,
+    ts.SyntaxKind.TryStatement,
+]);
+/**
+ * JS built-ins that are never a cloud resource. The rule guards resource
+ * declarations, so a guard clause like `if (bad) throw new Error(...)` — or a
+ * local `new Map()`/`new Set()` — must not be flagged as a control-flow resource.
+ */
+const NON_RESOURCE_CONSTRUCTORS = new Set([
+    "Error", "TypeError", "RangeError", "SyntaxError", "ReferenceError",
+    "EvalError", "URIError", "AggregateError",
+    "Map", "Set", "WeakMap", "WeakSet", "WeakRef", "Date", "RegExp", "Promise",
+    "Array", "Object", "String", "Number", "Boolean",
+]);
+/** The constructor identifier of a `new X(...)`, if it's a bare name. */
+function constructorName(node) {
+    return ts.isIdentifier(node.expression) ? node.expression.text : undefined;
+}
+function isInsideControlFlow(node) {
+    let current = node.parent;
+    while (current) {
+        if (CONTROL_FLOW_KINDS.has(current.kind))
+            return true;
+        current = current.parent;
+    }
+    return false;
+}
+function checkNode(node, context, diagnostics) {
+    if (ts.isNewExpression(node) && !NON_RESOURCE_CONSTRUCTORS.has(constructorName(node) ?? "")) {
+        if (isInsideControlFlow(node)) {
+            const { line, character } = context.sourceFile.getLineAndCharacterOfPosition(node.getStart(context.sourceFile));
+            diagnostics.push({
+                file: context.filePath,
+                line: line + 1,
+                column: character + 1,
+                ruleId: "EVL002",
+                severity: "error",
+                message: "Resource constructor inside control flow — resources must be unconditionally declared",
+            });
+        }
+    }
+    ts.forEachChild(node, (child) => checkNode(child, context, diagnostics));
+}
+export const evl002ControlFlowResourceRule = {
+    id: "EVL002",
+    severity: "error",
+    category: "correctness",
+    description: "Resource constructors must not appear inside control flow statements",
+    check(context) {
+        const diagnostics = [];
+        checkNode(context.sourceFile, context, diagnostics);
+        return diagnostics;
+    },
+};

package/dist/lint/rules/evl003-dynamic-property-access.js

@@ -0,0 +1,44 @@
+import * as ts from "typescript";
+import { isLiteralElementKey } from "../../fold/subset.js";
+/**
+ * EVL003: Dynamic Property Access
+ *
+ * Computed property access (obj[key]) must use a string or numeric literal key.
+ * Dynamic keys (variables, expressions) are not statically evaluable.
+ *
+ * Shares its key-shape predicate with `fold()`'s `elementKey()`
+ * ({@link "../../fold/fold"}) via {@link "../../fold/subset"} (#1024) — a
+ * dynamic element-access key is exactly the construct `fold()` rejects with
+ * `FoldError.ruleId === "EVL003"`, and the diagnostic is located at the key
+ * itself (not the whole `obj[key]` access), matching where `fold()`'s
+ * `elementKey()` throws — so a rejection and its EVL003 diagnostic cite the
+ * same position, not just the same rule id.
+ */
+function checkNode(node, context, diagnostics) {
+    if (ts.isElementAccessExpression(node)) {
+        const arg = node.argumentExpression;
+        if (!isLiteralElementKey(arg)) {
+            const { line, character } = context.sourceFile.getLineAndCharacterOfPosition(arg.getStart(context.sourceFile));
+            diagnostics.push({
+                file: context.filePath,
+                line: line + 1,
+                column: character + 1,
+                ruleId: "EVL003",
+                severity: "error",
+                message: "Dynamic property access — computed key must be a string or numeric literal",
+            });
+        }
+    }
+    ts.forEachChild(node, (child) => checkNode(child, context, diagnostics));
+}
+export const evl003DynamicPropertyAccessRule = {
+    id: "EVL003",
+    severity: "error",
+    category: "correctness",
+    description: "Computed property access must use a string or numeric literal key",
+    check(context) {
+        const diagnostics = [];
+        checkNode(context.sourceFile, context, diagnostics);
+        return diagnostics;
+    },
+};

package/dist/lint/rules/evl004-spread-non-const.js

@@ -0,0 +1,94 @@
+import * as ts from "typescript";
+import { isInsideCompositeFactory } from "./composite-scope.js";
+/**
+ * EVL004: Spread From Non-Const Source
+ *
+ * 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.
+ */
+function isTraceableToConst(node, sourceFile) {
+    // Object or array literals are fine
+    if (ts.isObjectLiteralExpression(node) || ts.isArrayLiteralExpression(node)) {
+        return true;
+    }
+    // Property access: follow the chain to the root
+    if (ts.isPropertyAccessExpression(node)) {
+        return isTraceableToConst(node.expression, sourceFile);
+    }
+    // Identifier — check if it's a const declaration
+    if (ts.isIdentifier(node)) {
+        return isConstIdentifier(node, sourceFile);
+    }
+    // Parenthesized
+    if (ts.isParenthesizedExpression(node)) {
+        return isTraceableToConst(node.expression, sourceFile);
+    }
+    // As/satisfies cast
+    if (ts.isAsExpression(node) || ts.isSatisfiesExpression(node)) {
+        return isTraceableToConst(node.expression, sourceFile);
+    }
+    return false;
+}
+function isConstIdentifier(id, sourceFile) {
+    // Walk all statements looking for a const declaration of this identifier
+    for (const stmt of sourceFile.statements) {
+        if (ts.isVariableStatement(stmt)) {
+            if (stmt.declarationList.flags & ts.NodeFlags.Const) {
+                for (const decl of stmt.declarationList.declarations) {
+                    if (ts.isIdentifier(decl.name) && decl.name.text === id.text) {
+                        return true;
+                    }
+                }
+            }
+        }
+    }
+    return false;
+}
+function checkNode(node, context, diagnostics) {
+    // Skip spreads inside Composite() factory callbacks
+    if (isInsideCompositeFactory(node)) {
+        ts.forEachChild(node, (child) => checkNode(child, context, diagnostics));
+        return;
+    }
+    // Spread in object literal: { ...expr }
+    if (ts.isSpreadAssignment(node)) {
+        if (!isTraceableToConst(node.expression, context.sourceFile)) {
+            const { line, character } = context.sourceFile.getLineAndCharacterOfPosition(node.getStart(context.sourceFile));
+            diagnostics.push({
+                file: context.filePath,
+                line: line + 1,
+                column: character + 1,
+                ruleId: "EVL004",
+                severity: "error",
+                message: "Spread from non-const source — spread expression must reference a const variable or literal",
+            });
+        }
+    }
+    // Spread in array literal: [...expr]
+    if (ts.isSpreadElement(node)) {
+        if (!isTraceableToConst(node.expression, context.sourceFile)) {
+            const { line, character } = context.sourceFile.getLineAndCharacterOfPosition(node.getStart(context.sourceFile));
+            diagnostics.push({
+                file: context.filePath,
+                line: line + 1,
+                column: character + 1,
+                ruleId: "EVL004",
+                severity: "error",
+                message: "Spread from non-const source — spread expression must reference a const variable or literal",
+            });
+        }
+    }
+    ts.forEachChild(node, (child) => checkNode(child, context, diagnostics));
+}
+export const evl004SpreadNonConstRule = {
+    id: "EVL004",
+    severity: "error",
+    category: "correctness",
+    description: "Spread expressions must reference a const variable or literal, not a dynamic source",
+    check(context) {
+        const diagnostics = [];
+        checkNode(context.sourceFile, context, diagnostics);
+        return diagnostics;
+    },
+};

package/dist/lint/rules/evl005-resource-block-body.js

@@ -0,0 +1,41 @@
+import * as ts from "typescript";
+/**
+ * EVL005: Block Body in resource() Callback
+ *
+ * The second argument to resource() must be an arrow function with an
+ * expression body: (props) => ({...}). Block bodies are not allowed
+ * because the evaluator expects an expression, not statements.
+ */
+function checkNode(node, context, diagnostics) {
+    if (ts.isCallExpression(node) &&
+        ts.isIdentifier(node.expression) &&
+        node.expression.text === "resource") {
+        // resource(Type, (props) => ({ ... })) — second arg is the factory
+        const factory = node.arguments[1];
+        if (factory && ts.isArrowFunction(factory)) {
+            if (ts.isBlock(factory.body)) {
+                const { line, character } = context.sourceFile.getLineAndCharacterOfPosition(factory.body.getStart(context.sourceFile));
+                diagnostics.push({
+                    file: context.filePath,
+                    line: line + 1,
+                    column: character + 1,
+                    ruleId: "EVL005",
+                    severity: "error",
+                    message: "Block body in resource() callback — use expression body: (props) => ({...})",
+                });
+            }
+        }
+    }
+    ts.forEachChild(node, (child) => checkNode(child, context, diagnostics));
+}
+export const evl005ResourceBlockBodyRule = {
+    id: "EVL005",
+    severity: "error",
+    category: "correctness",
+    description: "The resource() callback must use expression body, not block body",
+    check(context) {
+        const diagnostics = [];
+        checkNode(context.sourceFile, context, diagnostics);
+        return diagnostics;
+    },
+};