@intentius/tsad-conformance 1.4.0 → 1.6.0

package/fixtures/S-TopConst/an-unexported-const-is-a-binding/project/binding.ts

@@ -0,0 +1,3 @@
+const base = 21;
+
+export const x = base * 2;

package/fixtures/S-TopConst/an-unexported-const-is-a-binding/project/invisible.ts

@@ -0,0 +1,3 @@
+const { q } = { q: 1 };
+
+export const y = q;

package/fixtures/UNCOVERED.md

@@ -2,36 +2,9 @@
 
 Deliberate, and this list may only shrink (#8). Each entry names the rule and why it is still uncovered. Remove an entry when its fixture lands; the gate fails if an entry is stale.
 
-107 of 138 rules have fixtures. Most of the rules below are uncovered because the corpus is still growing (#24); where a rule needs something the reference implementation does not have, the entry says so.
+135 of 139 rules have fixtures. Every rule below needs something the reference implementation does not have, or something no adapter can observe; the entry says which.
 
-- `F-Rule-Input` — the harness has no rule hook and no findings-as-data fixture kind yet (#101)
-- `F-Rule-Phase` — the harness has no rule hook and no findings-as-data fixture kind yet (#101)
-- `F-Rule-Pure` — the harness has no rule hook and no findings-as-data fixture kind yet (#101)
-- `F-Rule-Finding` — the harness has no rule hook and no findings-as-data fixture kind yet (#101)
-- `F-Rule-Equivalence` — the harness has no rule hook and no findings-as-data fixture kind yet (#101)
-- `F-Rule-Supply` — the harness has no rule hook and no findings-as-data fixture kind yet (#101)
-- `F-Div-Step` — needs `{__compositeStep}`, which has no fate in the reference implementation (no composite factory form)
-- `F-Eval-Interior` — an unresolved chain inside an intrinsic call folds to a symbol only with a registry in scope, and an expression fixture names no host
-- `F-Host-Composite` — needs the composite registration form `Composite(fn, "N")`, which the reference implementation does not have
 - `F-Host-Generality` — says what a host may vary and what it may not; no verdict exercises it
-- `F-IsolatedRefusal` — needs isolation mode, which the reference implementation does not have
 - `F-NoOwnExecution` — measured by chant's `test/leftness` profile; an adapter reports verdicts and cannot observe execution
 - `F-NotProject` — a file inside the host's own module tree; the reference's project is a map with no outside
-- `F-Obs-Counters` — the conformance adapter exposes no counters
 - `F-Obs-Provenance` — an optional capability, reported rather than asserted
-- `F-Val-Domain` — no fixture yet; corpus is #24's
-- `F-Val-Envelope` — no fixture yet; corpus is #24's
-- `F-Val-Symbol-Scope` — no fixture yet; corpus is #24's
-- `S-Disqualify` — no fixture yet; corpus is #24's
-- `S-ExportDestructure` — no fixture yet; corpus is #24's
-- `S-ExportNamed` — no fixture yet; corpus is #24's
-- `S-ExportResource` — no fixture yet; corpus is #24's
-- `S-ExportSingle` — no fixture yet; corpus is #24's
-- `S-ExportTypeOnly` — no fixture yet; corpus is #24's
-- `S-FactoryBody` — needs the composite factory form, which the reference implementation does not have
-- `S-FactoryParams` — needs the composite factory form, which the reference implementation does not have
-- `S-Module` — no fixture yet; corpus is #24's
-- `S-Prop` — no fixture yet; corpus is #24's
-- `S-ReExport` — no fixture yet; corpus is #24's
-- `S-Shorthand` — no fixture yet; corpus is #24's
-- `S-TopConst` — no fixture yet; corpus is #24's

package/fixtures/roundtrip/a-resource-and-its-attribute/expect.json

@@ -0,0 +1,8 @@
+{
+  "rules": [
+    "F-Val-Source"
+  ],
+  "roundtrip": true,
+  "host": "shapes",
+  "note": "A resource with props and attributes, and attribute references to it at the top and nested. The generator names the same-file binding; F-Eval-Member step 1 folds the read back to the reference."
+}

package/fixtures/roundtrip/a-resource-and-its-attribute/value.json

@@ -0,0 +1,29 @@
+{
+  "logs": {
+    "__resource": "Bucket",
+    "props": {
+      "name": "logs",
+      "tags": [
+        "a",
+        "b"
+      ]
+    },
+    "attributes": {
+      "region": "eu"
+    }
+  },
+  "arn": {
+    "__attrRef": {
+      "entity": "logs",
+      "attribute": "arn"
+    }
+  },
+  "site": {
+    "origin": {
+      "__attrRef": {
+        "entity": "logs",
+        "attribute": "website"
+      }
+    }
+  }
+}

package/fixtures/roundtrip/a-resource-by-args/expect.json

@@ -0,0 +1,8 @@
+{
+  "rules": [
+    "F-Val-Source"
+  ],
+  "roundtrip": true,
+  "host": "shapes",
+  "note": "A resource whose constructor arguments are not (props) or (props, attributes): args is authoritative and the generator spreads it; props is the first object-literal argument, reported for readers and never re-passed (F-Val-Arity)."
+}

package/fixtures/roundtrip/a-resource-by-args/value.json

@@ -0,0 +1,14 @@
+{
+  "pair": {
+    "__resource": "Pair",
+    "props": {
+      "right": true
+    },
+    "args": [
+      "left",
+      {
+        "right": true
+      }
+    ]
+  }
+}

package/fixtures/roundtrip/intrinsics-and-a-symbol/expect.json

@@ -0,0 +1,8 @@
+{
+  "rules": [
+    "F-Val-Source"
+  ],
+  "roundtrip": true,
+  "host": "shapes",
+  "note": "Both intrinsic forms with a symbol, an attribute reference and a span that needs escaping inside them. A symbol has a form only inside an interior, which is where the generator puts it."
+}

package/fixtures/roundtrip/intrinsics-and-a-symbol/value.json

@@ -0,0 +1,36 @@
+{
+  "logs": {
+    "__resource": "Bucket",
+    "props": {
+      "name": "logs"
+    }
+  },
+  "tagged": {
+    "__intrinsic": "join",
+    "strings": [
+      "arn:",
+      ":",
+      "/`${x}`"
+    ],
+    "values": [
+      {
+        "__symbol": "Region.Name"
+      },
+      {
+        "__attrRef": {
+          "entity": "logs",
+          "attribute": "arn"
+        }
+      }
+    ]
+  },
+  "called": {
+    "__intrinsic": "ref",
+    "args": [
+      "logs",
+      {
+        "__symbol": "Stack.Id"
+      }
+    ]
+  }
+}

package/fixtures/roundtrip/scalars-and-containers/expect.json

@@ -0,0 +1,8 @@
+{
+  "rules": [
+    "F-Val-Source"
+  ],
+  "roundtrip": true,
+  "host": "shapes",
+  "note": "Every scalar, arrays and objects of them, a key that is not an identifier. The generator writes literals; the fold reads them back."
+}

package/fixtures/roundtrip/scalars-and-containers/value.json

@@ -0,0 +1,28 @@
+{
+  "scalars": {
+    "s": "text",
+    "n": 1.5,
+    "big": 1e+21,
+    "b": false,
+    "z": null,
+    "u": "$undefined"
+  },
+  "list": [
+    1,
+    "two",
+    [
+      3,
+      [
+        4
+      ]
+    ],
+    {
+      "five": 5
+    }
+  ],
+  "keys": {
+    "plain": 1,
+    "with-dash": 2,
+    "3": "three"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/tsad-conformance",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "The conformance suite of the typescript-as-data specification: fixture loader, runner, and the named hosts. An implementation supplies an adapter and gets a report.",
   "license": "Apache-2.0",
   "repository": {

package/spec/VERSION

@@ -1 +1 @@
-1.4
+1.6

package/spec/hosts.md

@@ -90,8 +90,12 @@ helpers and `propagate` mutates in place; `createResource()`/
 
 A call into a **package** folds only through a closed allowlist, a
 registered intrinsic or helper, checked by name *and* by the provenance of
-the binding (R3.3, F-Div-Provenance). A call into a **project file** folds
-whenever the callee's body is itself in the subset (R6.5), with no allowlist.
+the binding (R3.3, F-Div-Provenance), or at a declarator by invocation
+(F-Call), reached directly or through a const alias (F-Declarator), where
+since `1.6` the result is a value whatever it is. A call nested inside an
+expression never folds through a package. A call into a **project file**
+folds whenever the callee's body is itself in the subset (R6.5), with no
+allowlist.
 
 The asymmetry is the trust boundary (R2.1, #36). Package code is already
 loaded and executed by the build before discovery begins; admitting a call

package/spec/judgments.md

@@ -63,6 +63,7 @@ another language embeds, or a JavaScript tool that folds and never runs. It is
 | `F-Val-Fate` | altered: revival is serialization. An envelope is the output; `{__resource}`, `{__intrinsic}` and `{__attrRef}` reach the artifact as data for the host's serializer to map. No constructor and no function is invoked |
 | `F-Eval-CallHelper`, `F-Eval-CallEager`, `F-Host-Admission`, `F-Host-NoSubstitution` | absent: there is nothing to invoke. A registered helper or eager name is an ordinary unresolved identifier |
 | `F-Eval-Tagged`, `F-Eval-CallIntrinsic` | apply; the envelope stays an envelope |
+| `F-Val-Source` | applies, and the round trip is `fold(generate(v)) = v` literally: no fate runs, so the fold of a form is the envelope itself. The helper and composite-step cases are absent with their rules |
 | `F-Call`, `F-Host-Composite` | interpretation only (step 4). A factory that is not interpretable is an error, never invoked |
 | `S-LocalFunction`, `S-CallLocal` | apply in full: a same-file or project-imported function is called by interpretation, which needs no runtime |
 | `S-ExportDefault` | applies: a default export is the declarator named `default`. In `full` it is permitted, not required, and chant does not yet admit it |
@@ -331,11 +332,23 @@ F-IsolatedRefusal like any other.
   here; a second construction would put two entities where running puts one
   (F-Count). Under `isolated`, a `T` from a project file is
   F-IsolatedRefusal.
-- *single* `export const x = e`: if `e` is a call, F-Call; if a member or
-  element access on a call's result, F-Call then index (base must be an
-  indexable object); otherwise J1 on `e`, revived.
-- *destructure* `export const { a, b: c } = e`: `e` must resolve to a
-  composite instance or an indexable object; each element indexes it.
+- *single* `export const x = e`: if `e` is a call, its direct arguments are
+  resolved first. An argument that is itself a package call resolves by
+  F-Call, as does a member read on such a call or a const alias of either;
+  every other argument is J1's (`1.6`, #110, `L2.18`). Then the call is
+  F-Call for an unregistered callee, or J1's registered form for a helper or
+  an intrinsic. If `e` is a member or element access on a
+  call's result, F-Call then index (base must be an indexable object); when
+  `e` is an identifier bound by a top-level `const`,
+  through any chain of such aliases (`L7.7`), to a call or to a member access
+  on one, the same again, with the call resolved once per file (F-Count);
+  otherwise J1 on `e`, revived. The alias case was added in `1.6` (#110),
+  since chant had followed it for a composite and for any package export
+  alike (`L2.18`); a call reached any other way, nested inside an expression,
+  stays J1's rejection.
+- *destructure* `export const { a, b: c } = e`: `e`, through the same
+  aliases, must resolve to a composite instance or an indexable object; each
+  element indexes it.
 - *named-export* `export { a, b as c }`: each local name resolves through
   `locals` then `externals`, by F-Eval-Ident and not by re-folding the
   initializer, so a name bound to a same-file `new` reads F-Prebuild's
@@ -361,10 +374,14 @@ F-IsolatedRefusal like any other.
 6. Otherwise the module is imported (once per build) and `c` **invoked** with
    the resolved arguments; `factoryInvocations += 1`, and
    `projectFactoryInvocations += 1` if the specifier is a project file.
-   Arguments that are live objects pass through unchanged; a `{__attrRef}`
-   among them stays symbolic (R1.2, L6.9).
-7. The result must be a `CompositeInstance` or a `Declarable`; otherwise
-   `run`.
+   An argument is resolved as F-Declarator says, a direct package call by
+   this rule in turn and the rest by J1; a call nested deeper inside an
+   argument is J1's rejection. Arguments that are live objects pass
+   through unchanged; a `{__attrRef}` among them stays symbolic (R1.2, `L6.9`).
+7. The result is a value, live or plain, and is what the declarator binds
+   (`1.6`, #110); a destructured declarator needs an indexable object
+   (F-Declarator). Before `1.6` the text required an entity or a composite
+   instance here, which chant never implemented (`L8.19`).
 
 **F-Count.** Within `f`, a composite call reached by several member accesses
 or destructured names is resolved once (`ResolveCtx.memo`); a same-file
@@ -879,7 +896,7 @@ position and calls through a bare identifier. A body that references one of
 its module's own module-level resources declines (L7.6), that resource is a
 singleton the run path shares, and interpretation would not, and
 `constResolvesToResource` follows alias chains so it cannot be smuggled in
-(L7.7). The defining module is never imported; members are built by the
+(`L7.7`). The defining module is never imported; members are built by the
 lexicon's constructors from the folded props.
 
 **F-Eval-CallEager, F-Eval-CallMethod** *(was R7.3. Evaluate eagerly)*

package/spec/rules.md

@@ -96,7 +96,10 @@ refuses to load one into its own process while the sandbox is armed and
 runs it in the child instead (chant#1131), which is the isolation mode's
 boundary drawn once more around rules.
 
-**Fixtures.** No `F-Rule-*` rule has a fixture yet: the harness has no hook
-that runs a rule and no fixture kind whose expectation is a finding. That
-work is #101; until it lands the family is listed in `fixtures/UNCOVERED.md`
-with that reason.
+The fixtures for this family carry the finding as data and not the rule,
+since a rule is host code (#101): the `shapes` host names two rules by id and
+phase, a fixture's `findings` says what they report, and an implementation
+that carries no rule of that id says so and is skipped visibly. The runner
+asks for each phase twice and holds the two runs to the same answer, which
+is F-Rule-Pure tested before anything else, and `compareAdapters` holds two
+implementations to the same findings, which is F-Rule-Equivalence.

package/spec/values.md

@@ -132,6 +132,32 @@ arguments (`foldIntrinsicValue`). Anywhere else an unresolved chain is a
 located rejection (F-Reference, J2). A `__symbol` therefore never appears at
 the top of a folded tree.
 
+## F-Val-Source (every value has a source form)
+
+For every value `v` of F-Val-Domain there is source in the subset
+(grammar.md) whose fold, in the profile named, is `v`. The table names one
+such form per case, which is the form a generator should prefer and not the
+only one the subset admits; the rule was added in `1.5` (#80).
+
+| Case | A source form that folds to it | In |
+|---|---|---|
+| scalar | the literal: `"s"`, `1.5`, `true`, `null`, `undefined` (F-Eval-Literal, F-Eval-Undefined) | both |
+| array, object | the literal, with each member's source form as its element or value; a key that is not an identifier is a string key (S-Prop) | both |
+| attribute reference `{__attrRef: {entity, attribute}}` | `entity.attribute`, where `entity` is a same-file `const` bound to a `new` (F-Eval-Member step 1, F-Prebuild) | both |
+| intrinsic, tag form `{__intrinsic, strings, values}` | the tagged template `name\`s₀${v₀}s₁…\`` for a registered tag (F-Eval-Tagged) | both |
+| intrinsic, call form `{__intrinsic, args}` | `name(args…)` for an intrinsic registered with `foldsAsCall` (F-Eval-CallIntrinsic) | both |
+| helper call `{__helper, args}` | `name(args…)` for a registered helper (F-Eval-CallHelper). J1 yields the envelope and revival invokes the helper, so the envelope is never the output | `full` |
+| resource `{__resource, props, attributes?, args?}` | `new C(props)`, `new C(props, attributes)`, or `new C(…args)` when `args` is present (F-Eval-New, F-Val-Arity) | both |
+| composite step `{__compositeStep, args}` | the interpretable factory form (F-Host-Composite) | `full` |
+| symbol `{__symbol}` | the unresolved chain, written inside an intrinsic's interior (F-Eval-Interior, F-Val-Symbol-Scope) | both |
+
+Nothing else is a value, so nothing else needs a form, and the fold of a
+form in `full` is the value after F-Val-Fate, so a resource's form folds to a
+live instance there and to the envelope in `data-host`; the round trip
+(README.md, "the generator obligation") is stated per profile for that
+reason. A live instance has no source form of its own: its form is the
+envelope's.
+
 ---
 
 ## Rationale
@@ -144,8 +170,9 @@ The spec must define what a fold produces. Every other requirement quantifies
 over it, and it is currently defined only by a TypeScript union
 (`FoldedValue`, `fold.ts:116`; L4.1).
 
-Nine cases. Six are ordinary JSON, string, number, boolean, null, undefined,
-arrays and plain objects. The rest carry envelopes:
+There are nine cases, and six of them are ordinary JSON, the scalars with
+`undefined` beside them, plus arrays and plain objects. The rest carry
+envelopes:
 
 | Case | Envelope key | Denotes | Fate (R1.2) |
 |---|---|---|---|
@@ -157,6 +184,24 @@ arrays and plain objects. The rest carry envelopes:
 | `FoldedCompositeStepCall` | `__compositeStep` | `<Identifier>(...).step`, member fixed | revived |
 | `SymbolicValue` | `__symbol` | source text preserved inside an intrinsic interior | revived |
 
+**F-Val-Source.** The round trip, `fold(generate(v)) = v`, is what makes
+the choice of language a matter of correctness. A generator decides what
+each value is: this string is a literal and that one is a reference to
+another resource's attribute, while a repetition across forty resources is
+one `const`. Each decision needs a form the subset can express and the fold
+reverses, and the rule is the completeness half of that property, written
+as a table rather than a sentence so that a generator author can read off a
+form per case. The two open questions on #80 are settled here as follows.
+The table names one form per case and requires only that one exists, so
+generators stay comparable without being constrained to agree; and the
+property is stated per profile, because in `full` the fold of a resource's
+form is a live instance and not the envelope. chant's three generators, `chant import` from a template,
+`--from` live import and carve-out from Terraform, emit through one
+pipeline (`L12.1`) whose forms are the table's; its Kubernetes round-trip
+suite compares resource count and kinds after re-serialization and not
+bytes (`L12.4`), so the byte-level measurement the paper wants is still to be
+taken.
+
 **F-Val-Envelope** *(was R1.1. Symbolic is not unevaluated)*
 
 An `__attrRef` is not a thunk. It is the envelope `AttrRef.prototype.toJSON()`

package/src/adapter.ts

@@ -22,8 +22,42 @@ export interface ProjectResult {
   tentative?: Record<string, "fold" | "run">;
   /** For a file J3 tainted, the file whose taint reached it. */
   taintedBy?: Record<string, string>;
+  /** F-Obs-Counters, per build. Omitted by an implementation whose public entry exposes none. */
+  counters?: ExecutionCounters;
 }
 
+/**
+ * F-Obs-Counters: in-process factory or constructor invocations while folding;
+ * of those, how many resolved to project-owned code; and how many factory
+ * bodies were interpreted instead. Three non-negative integers; the names
+ * follow the reference and only the shape is normative.
+ */
+export interface ExecutionCounters { factoryInvocations: number; projectFactoryInvocations: number; factoryInterpretations: number }
+
+/** F-Rule-Finding's closed severity set. */
+export type Severity = "error" | "warning" | "info";
+/** F-Rule-Phase: named by the input the rule reads, the folded namespace or the artifact. */
+export type RulePhase = "pre" | "post";
+/**
+ * A finding, as data (F-Rule-Finding). `rule`, `severity` and `subject` are
+ * compared; `message` is not (F-Obs-Messages); `at` only when the fixture
+ * gives one and the implementation reports one (F-Obs-Provenance is
+ * optional). `file` names the file whose namespace holds the subject for a
+ * pre-synthesis finding; a post-synthesis finding concerns the artifact and
+ * carries none.
+ */
+export interface Finding {
+  rule: string;
+  severity: Severity;
+  subject: string;
+  message: string;
+  file?: string;
+  at?: { line: number; column: number };
+}
+
+/** J2's ι (F-IsolatedRefusal): under `isolated`, no project code is invoked or imported on the fold path. */
+export type IsolationMode = "open" | "isolated";
+
 export interface ConformanceAdapter {
   readonly name: string;
   /**
@@ -48,5 +82,24 @@ export interface ConformanceAdapter {
   foldProject?(
     files: Map<string, string>,
     host?: ConformanceHost,
+    mode?: IsolationMode,
   ): ProjectResult | "unavailable" | Promise<ProjectResult | "unavailable">;
+  /**
+   * The findings of the host's rules of one phase over the build (#101).
+   * A rule is host code, so the harness carries only its identifier and its
+   * findings; an implementation that cannot run a rule the host names
+   * reports "unavailable" and the fixture is skipped visibly.
+   */
+  rules?(
+    files: Map<string, string>,
+    host: ConformanceHost,
+    phase: RulePhase,
+  ): Finding[] | "unavailable" | Promise<Finding[] | "unavailable">;
+  /**
+   * The round trip's generator (#80): source in the subset, as one module,
+   * whose fold is `namespace` (export name to value, envelopes included).
+   * "unavailable" for an implementation with no generator, or for a value it
+   * has no form for; F-Val-Source says a form exists for every value.
+   */
+  generate?(namespace: Record<string, unknown>, host?: ConformanceHost): string | "unavailable";
 }