@dotzen/dotzen 0.0.1 → 0.0.3

package/README.md

@@ -22,13 +22,37 @@ export const spec = [
 
 Each finding is `block` (fails the build), `warn`, or `require_approval` (pauses CI for sign-off). When a value can't be resolved statically, dotzen reports **"could not evaluate"** rather than guessing — a false positive is worse than an honest gap.
 
+**Org-specific tags:** tag taxonomies vary by org, so `mustHaveTags` accepts your own keys — declare them in your own `enum` (keeps typos as compile errors) and mix with the built-in `Tag`:
+
+```ts
+enum OrgTag {
+  ApmId = 'apm_id',
+  CmdbAppId = 'cmdb_app_id',
+}
+rule()
+  .resource(AwsResource.S3Bucket)
+  .mustHaveTags(OrgTag.ApmId, OrgTag.CmdbAppId, Tag.Environment)
+  .message('...')
+```
+
+dotzen resolves tags through `var`/`local` refs and `merge(<literal>, var.tags)` — so a required key hardcoded in the module passes, while one that might come from a caller's `var.tags` reports "could not evaluate" (never a false violation).
+
 ## Getting started
 
 ```bash
 npx @dotzen/dotzen init      # scaffold .zen/spec.ts + dotzen.json
+npm i -D @dotzen/dotzen      # editor autocomplete + type-checking for spec.ts
 npx @dotzen/dotzen check     # evaluate ./terraform against the spec
 ```
 
+Two modes, both supported:
+
+- **Authoring** — install as a devDependency so your editor resolves the
+  DSL types (`import { rule } from '@dotzen/dotzen'`) and gives you
+  autocomplete + compile-time safety while you write rules.
+- **Running** — `npx @dotzen/dotzen check` stays zero-install (nothing to add
+  to your project) — ideal for CI. The engine resolves the DSL import itself.
+
 - `--format json` for machine-readable output.
 - Pin the version in `dotzen.json` (never `@latest` in CI).
 

package/dist/cli/main.js

@@ -96,6 +96,9 @@ function runInit(dir, terraform) {
         process.stdout.write(`  created  ${c}\n`);
     for (const s of res.skipped)
         process.stdout.write(`  skipped  ${s} (already exists)\n`);
+    process.stdout.write('\nFor editor autocomplete + type-checking of .zen/spec.ts, install the\n' +
+        'types locally:  npm i -D @dotzen/dotzen   (and add node_modules/ to\n' +
+        '.gitignore). Running `check` via npx needs no local install.\n');
     if (res.detected) {
         const roots = Array.isArray(res.terraform) ? res.terraform : [res.terraform];
         const fmt = (r) => typeof r === 'string' ? `"${r}"` : `"${r.path}" (${r.environment})`;

package/dist/engine/evaluate.js

@@ -117,9 +117,17 @@ function evalMustHaveTags(c, r) {
         };
     const present = new Set(r.tags.keys);
     const missing = c.tags.filter((t) => !present.has(t));
-    if (missing.length > 0)
-        return { kind: 'violation', detail: `missing tags: ${missing.join(', ')}` };
-    return { kind: 'pass' };
+    if (missing.length === 0)
+        return { kind: 'pass' };
+    // A `partial` set (e.g. merge(<literal>, var.tags)) proves presence but not
+    // absence — a var arg may supply the missing key, so don't claim a
+    // violation; degrade honestly instead.
+    if (r.tags.kind === 'partial')
+        return {
+            kind: 'cannotEvaluate',
+            reason: `tag(s) not in the resolvable portion (a var/merge arg may add them): ${missing.join(', ')}`,
+        };
+    return { kind: 'violation', detail: `missing tags: ${missing.join(', ')}` };
 }
 const isLiteralTrue = (v) => v?.kind === 'literal' && v.value === true;
 /**

package/dist/hcl/model.d.ts

@@ -24,6 +24,9 @@ export interface IngressRule {
 export type TagsInfo = {
     readonly kind: 'resolved';
     readonly keys: string[];
+} | {
+    readonly kind: 'partial';
+    readonly keys: string[];
 } | {
     readonly kind: 'unresolved';
 };

package/dist/hcl/normalize.js

@@ -284,20 +284,63 @@ function egressFor(block, scope) {
         ...dynamicBlocks(block, 'egress', scope),
     ];
 }
+// Object-literal keys (`ident = …`) in an HCL expression string. A single
+// `=` (not `==`/`>=`/etc.) is HCL's attribute-assignment operator, so this
+// reliably picks up flat map keys inside a `merge(...)` argument.
+const OBJECT_KEY = /([A-Za-z_][A-Za-z0-9_-]*)\s*=(?!=)/g;
+// `var.x` / `local.y` reference tokens mentioned in an expression.
+const REF_TOKEN = /\b(var|local)\.([A-Za-z0-9_-]+)/g;
 /**
- * Tags: a literal map gives us the present keys; a `${...}` expression
- * (var/merge/local) is unresolved; an absent block is resolved-but-empty
- * (the literal AI-generated case — no tags written means none present).
+ * Keys known to be present on a tags value, and whether that set is
+ * COMPLETE. Follows sole `var`/`local` references to their value, and
+ * unions the literal keys (and resolvable refs) inside a `merge(...)`.
+ * Returns `null` when nothing can be determined (an unresolvable reference
+ * or an opaque expression) — which becomes "could not evaluate".
  */
-function tagsOf(block) {
-    const t = block?.tags;
-    if (t === undefined)
-        return { kind: 'resolved', keys: [] };
-    if (typeof t === 'string' && isInterpolated(t))
+function tagKeys(value, scope, depth = 8) {
+    if (value === undefined)
+        return { keys: [], complete: true };
+    if (value && typeof value === 'object' && !Array.isArray(value))
+        return { keys: Object.keys(value), complete: true };
+    if (typeof value !== 'string')
+        return null;
+    const ref = SOLE_REF.exec(value); // exactly one ${var.x} / ${local.y}
+    if (ref) {
+        if (depth <= 0)
+            return null;
+        const key = `${ref[1]}.${ref[2]}`;
+        return scope.has(key) ? tagKeys(scope.get(key), scope, depth - 1) : null;
+    }
+    if (/\bmerge\s*\(/.test(value)) {
+        // merge() only ever ADDS keys, so presence is monotonic. Collect the
+        // inline literal keys plus keys from any resolvable ref args; mark the
+        // set incomplete (a var/unresolved arg may contribute more).
+        const keys = new Set(value.match(OBJECT_KEY)?.map((m) => m.replace(/\s*=$/, '')) ?? []);
+        for (const [, kind, name] of value.matchAll(REF_TOKEN)) {
+            const scopeKey = `${kind}.${name}`;
+            if (depth > 0 && scope.has(scopeKey)) {
+                const sub = tagKeys(scope.get(scopeKey), scope, depth - 1);
+                if (sub)
+                    for (const k of sub.keys)
+                        keys.add(k);
+            }
+        }
+        return { keys: [...keys], complete: false };
+    }
+    return null; // some other unresolvable expression
+}
+/**
+ * Tags: a literal map (or a `var`/`local` reference resolved to one) gives
+ * a complete key set; `merge(<literal>, var.tags)` gives a PARTIAL set
+ * (known-present keys, may be more); anything else is unresolved.
+ */
+function tagsOf(block, scope) {
+    const r = tagKeys(block?.tags, scope);
+    if (r === null)
         return { kind: 'unresolved' };
-    if (t && typeof t === 'object' && !Array.isArray(t))
-        return { kind: 'resolved', keys: Object.keys(t) };
-    return { kind: 'unresolved' };
+    return r.complete
+        ? { kind: 'resolved', keys: r.keys }
+        : { kind: 'partial', keys: r.keys };
 }
 /** Resolved value of the `environment` tag (for rule scoping), if present. */
 function environmentOf(block, scope) {
@@ -445,7 +488,7 @@ function normalize(parsed, file, rawText, scope = new Map(), environmentOverride
                 line: findLine(rawText, type, name),
                 ingress: ingressFor(type, block, scope),
                 egress: egressFor(block, scope),
-                tags: tagsOf(block),
+                tags: tagsOf(block, scope),
                 attributes: extracted.attributes,
                 lists: extracted.lists,
                 blocks: extracted.blocks,

package/dist/spec/load.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.importSpecModule = importSpecModule;
 exports.loadSpec = loadSpec;
 const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
 const jiti_1 = require("jiti");
 const result_1 = require("../result/result");
 /**
@@ -47,7 +48,16 @@ async function importSpecModule(specPath) {
     if (!fs.existsSync(specPath))
         return (0, result_1.err)({ kind: 'ConfigNotFound', path: specPath });
     try {
-        const jiti = (0, jiti_1.createJiti)(__filename);
+        // A scaffolded spec imports `@dotzen/dotzen`, but under `npx` the engine
+        // runs from the npx cache while the user's project has no local install —
+        // so that bare specifier won't resolve from the spec's location. Alias it
+        // to THIS running engine's own barrel (dist/index.js at runtime, or
+        // src/index.ts under the test transpiler — extension-less so jiti picks
+        // the right one). This is what makes the zero-install `npx` flow work.
+        const enginePath = path.join(__dirname, '..', 'index');
+        const jiti = (0, jiti_1.createJiti)(__filename, {
+            alias: { '@dotzen/dotzen': enginePath },
+        });
         const mod = (await jiti.import(specPath));
         const spec = mod.spec;
         if (!Array.isArray(spec))

package/dist/spec/rule.d.ts

@@ -18,7 +18,7 @@ export type Condition = {
     readonly from: Cidr[];
 } | {
     readonly kind: 'mustHaveTags';
-    readonly tags: Tag[];
+    readonly tags: string[];
 } | {
     readonly kind: 'mustBeTrue';
     readonly attrs: AnyAttribute[];
@@ -112,7 +112,19 @@ export declare class RuleBuilder {
     environment(env: Environment): this;
     denyIngress(...ports: Port[]): this;
     denyEgress(...ports: Port[]): this;
-    mustHaveTags(...tags: Tag[]): this;
+    /**
+     * Required tag KEYS. Accepts the built-in `Tag` enum AND org-specific
+     * keys — because tag taxonomies are org-defined, unlike cloud-fixed
+     * resource types/ports. Always back org keys with your OWN `enum` (never
+     * bare strings) so typos stay compile errors:
+     *
+     *   enum OrgTag { ApmId = 'apm_id', CmdbAppId = 'cmdb_app_id' }
+     *   rule().resource(...).mustHaveTags(OrgTag.ApmId, Tag.Environment)
+     *
+     * The `string & {}` keeps `Tag` autocomplete while allowing your enum's
+     * (string-valued) members through.
+     */
+    mustHaveTags(...tags: (Tag | (string & {}))[]): this;
     mustBeTrue(...attrs: AnyAttribute[]): this;
     /** AnyAttribute must be explicitly false; absent counts as a violation
      *  (use for attributes whose insecure AWS default is `true`). */

package/dist/spec/rule.js

@@ -44,6 +44,18 @@ class RuleBuilder {
         });
         return this;
     }
+    /**
+     * Required tag KEYS. Accepts the built-in `Tag` enum AND org-specific
+     * keys — because tag taxonomies are org-defined, unlike cloud-fixed
+     * resource types/ports. Always back org keys with your OWN `enum` (never
+     * bare strings) so typos stay compile errors:
+     *
+     *   enum OrgTag { ApmId = 'apm_id', CmdbAppId = 'cmdb_app_id' }
+     *   rule().resource(...).mustHaveTags(OrgTag.ApmId, Tag.Environment)
+     *
+     * The `string & {}` keeps `Tag` autocomplete while allowing your enum's
+     * (string-valued) members through.
+     */
     mustHaveTags(...tags) {
         this._conditions.push({ kind: 'mustHaveTags', tags });
         return this;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotzen/dotzen",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Prose as Code — governance for AI-generated Terraform (AWS, Azure, GCP).",
   "license": "MIT",
   "keywords": [