@intentius/chant 0.124.51 → 0.124.54

package/dist/lifecycle/index-import.d.ts

@@ -0,0 +1,168 @@
+import type { IREdge, IRNode } from "../graph-ir.js";
+import type { ParameterIR, TemplateIR } from "../import/parser.js";
+import { type DeclaredEntity, type IndexIdentity } from "./identity-match.js";
+import type { IndexDocument } from "./index-document.js";
+/** What to import from the index. Within one field any value matches; every field given must match. */
+export interface IndexImportSelection {
+    /** Listed types or lexicon kinds (`AWS::S3::Bucket`). */
+    types?: readonly string[];
+    /** Native ids or node ids. */
+    names?: readonly string[];
+    /** Tags the node carries, every one with this value. */
+    tags?: Readonly<Record<string, string>>;
+    /** Node ids, a subgraph from a query (`chant search --index ... --json`). */
+    nodes?: readonly string[];
+    /** Every node in the index. */
+    all?: boolean;
+}
+/** An imported node as a reference target. */
+export interface IndexImportTarget {
+    logicalId: string;
+    node: IRNode;
+}
+/**
+ * A lexicon's index import seam (a plugin's `indexImport`). Data plus pure
+ * functions that turn an indexed node into the lexicon's own import IR
+ * ({@link ResourceIR}), which its `templateGenerator()` then writes.
+ */
+export interface IndexImportCodegen {
+    /**
+     * The resource for one indexed node: its import IR type and the
+     * properties a declaration can hold (server-assigned fields left out), or
+     * why the node cannot be written. `attributes` are resource-level
+     * attributes under the lexicon's own keys (the aws lexicon writes
+     * `DeletionPolicy: Retain` on every imported resource, #4536).
+     */
+    resource(node: IRNode): {
+        type: string;
+        properties: Record<string, unknown>;
+        attributes?: Record<string, unknown>;
+    } | {
+        unsupported: string;
+    };
+    /**
+     * `value`, held by another node, as a reference to `target` in this
+     * lexicon's IR, or undefined when the value is not one the lexicon can
+     * spell as a reference (it then stays a literal).
+     */
+    reference(value: string, target: IndexImportTarget): unknown | undefined;
+    /** The parameter that stands in for a masked value. */
+    secretParameter(name: string, context: {
+        node: IRNode;
+        logicalId: string;
+        path: string;
+    }): ParameterIR;
+    /** A reference to that parameter, as a property value in this lexicon's IR. */
+    parameterReference(name: string): unknown;
+    /** The type's short name for logical ids (`Bucket` for `AWS::S3::Bucket`). Absent: the kind's last segment. */
+    typeLabel?(node: IRNode): string;
+}
+/** What {@link planIndexImport} needs from a lexicon. A `LexiconPlugin` is one. */
+export interface IndexImportLexicon {
+    name: string;
+    indexImport?: IndexImportCodegen;
+}
+/** One reference a node holds, as the import wrote it. */
+export interface IndexImportReference {
+    path: string;
+    target: string;
+    rule?: string;
+    written: "reference" | "literal";
+    /** Why a literal stayed a literal. */
+    reason?: string;
+}
+/** One selected resource in the report. */
+export interface IndexImportResourceReport {
+    node: string;
+    identity: {
+        substrate: string;
+        scopeId: string;
+        listedType: string;
+        location: string;
+        nativeId: string;
+    };
+    cloudIds: Array<{
+        kind: string;
+        value: string;
+    }>;
+    /** The ownership markers the listing read off the resource, when any. */
+    markers?: unknown;
+    lexicon: string;
+    kind: string;
+    status: "imported" | "declared" | "unsupported";
+    reason?: string;
+    /** With `declared`: the entity the matcher bound to it. */
+    entity?: string;
+    /** With `imported`: the logical id and the group's directory (`""` is the output root). */
+    logicalId?: string;
+    group?: string;
+    references?: IndexImportReference[];
+    parameters?: string[];
+}
+export interface IndexImportParameterReport {
+    name: string;
+    node: string;
+    path: string;
+    group: string;
+}
+/** The import report (`chant-index-import.json`), deterministic for one index and selection. */
+export interface IndexImportReport {
+    report: "chant-index-import/v1";
+    index: Array<{
+        scopeKey: string;
+        observedAt: string;
+        digest: string;
+        source: string;
+    }>;
+    selection: IndexImportSelection;
+    resources: IndexImportResourceReport[];
+    parameters: IndexImportParameterReport[];
+    groups: Array<{
+        group: string;
+        lexicon: string;
+        location: string;
+        resources: number;
+    }>;
+}
+/** One output group: a lexicon and a location, written to `dir` under the output. */
+export interface IndexImportGroup {
+    /** `""` when the import has one group, else `<lexicon>/<location>`. */
+    dir: string;
+    lexicon: string;
+    location: string;
+    ir: TemplateIR;
+    /** Comment lines (without `// `) to put at the top of the group's first file. */
+    header: string[];
+}
+export interface IndexImportPlan {
+    groups: IndexImportGroup[];
+    report: IndexImportReport;
+}
+export interface PlanOptions {
+    /** Node id -> declared entity name, from {@link declaredNodes}. */
+    declared?: ReadonlyMap<string, string>;
+}
+/** True when the selection names nothing: no `all` and no filter. An empty selection selects no node. */
+export declare function selectionIsEmpty(sel: IndexImportSelection): boolean;
+/** Whether a node is selected. */
+export declare function nodeSelected(node: IRNode, sel: IndexImportSelection): boolean;
+/**
+ * The indexed nodes the project already declares, keyed by node id, with
+ * the entity's name: the identity matcher (#4523) run once per location the
+ * index holds, for each lexicon that declares an `indexIdentity`. A node two
+ * entities bind keeps the first by entity name.
+ */
+export declare function declaredNodes(docs: readonly IndexDocument[], entitiesByLexicon: ReadonlyMap<string, readonly DeclaredEntity[]>, identities: ReadonlyArray<{
+    name: string;
+    indexIdentity?: IndexIdentity;
+}>): Map<string, string>;
+/** The path a derived edge's rule names on its holder, or undefined (identity-match and tag rules name none). */
+export declare function edgeRulePath(edge: IREdge, holder: IRNode): string | undefined;
+/**
+ * Plan an import from the documents of one index read. Pure; throws only on
+ * documents from two accounts or two reads, as derive-edges.ts does.
+ */
+export declare function planIndexImport(docs: readonly IndexDocument[], selection: IndexImportSelection, lexicons: readonly IndexImportLexicon[], options?: PlanOptions): IndexImportPlan;
+/** The header comment for a group's first file. Same plan, same text. */
+export declare function indexImportHeader(plan: IndexImportPlan, group: IndexImportGroup): string;
+//# sourceMappingURL=index-import.d.ts.map

package/dist/lifecycle/index-import.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-import.d.ts","sourceRoot":"","sources":["../../src/lifecycle/index-import.ts"],"names":[],"mappings":"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"}