@huaweidevtools/aishell-dsh-deploy 0.0.15 → 0.0.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. package/README.md +28 -9
  2. package/cordis.patch.yml +12 -3
  3. package/lib/data/permission-registry.json +1 -1
  4. package/lib/index.js +6163 -1474
  5. package/lib/types/auth-http.d.ts +36 -4
  6. package/lib/types/auth-obs-signer.d.ts +8 -5
  7. package/lib/types/auth-signer.d.ts +6 -1
  8. package/lib/types/bridge.d.ts +20 -5
  9. package/lib/types/bss.d.ts +159 -0
  10. package/lib/types/catalog.d.ts +118 -0
  11. package/lib/types/credentials.d.ts +64 -18
  12. package/lib/types/d2-design.d.ts +60 -0
  13. package/lib/types/d2-engine.d.ts +111 -0
  14. package/lib/types/d2-inventory.d.ts +54 -0
  15. package/lib/types/data-paths.d.ts +10 -0
  16. package/lib/types/deployment-state.d.ts +90 -13
  17. package/lib/types/existing-topology.d.ts +154 -0
  18. package/lib/types/existing.d.ts +100 -0
  19. package/lib/types/gates/cost_gate.d.ts +38 -16
  20. package/lib/types/gates/credential_gate.d.ts +29 -3
  21. package/lib/types/gates/design_gate.d.ts +72 -0
  22. package/lib/types/gates/mirror.d.ts +1 -1
  23. package/lib/types/gates/plan_gate.d.ts +116 -0
  24. package/lib/types/gates/provider_installed.d.ts +32 -0
  25. package/lib/types/gates/terraform_env.d.ts +16 -3
  26. package/lib/types/hcl.d.ts +176 -0
  27. package/lib/types/index.d.ts +18 -4
  28. package/lib/types/inventory-subnets.d.ts +78 -0
  29. package/lib/types/network-checks.d.ts +67 -0
  30. package/lib/types/paths.d.ts +51 -0
  31. package/lib/types/permission/gate.d.ts +6 -6
  32. package/lib/types/permission/registry.d.ts +11 -0
  33. package/lib/types/plan.d.ts +68 -0
  34. package/lib/types/projects.d.ts +40 -0
  35. package/lib/types/prompt.d.ts +5 -4
  36. package/lib/types/rating-map.d.ts +132 -0
  37. package/lib/types/security-groups.d.ts +16 -23
  38. package/lib/types/terraform-run.d.ts +32 -0
  39. package/lib/types/tools/annotations.d.ts +1 -1
  40. package/lib/types/tools/balance_summary.d.ts +1 -1
  41. package/lib/types/tools/deployment.d.ts +3 -3
  42. package/lib/types/tools/design.d.ts +54 -0
  43. package/lib/types/tools/errors.d.ts +22 -4
  44. package/lib/types/tools/examples.d.ts +1 -1
  45. package/lib/types/tools/existing_resources.d.ts +1 -1
  46. package/lib/types/tools/index.d.ts +26 -12
  47. package/lib/types/tools/openapi.d.ts +19 -9
  48. package/lib/types/tools/pricing.d.ts +213 -0
  49. package/lib/types/tools/provider_schema.d.ts +1 -1
  50. package/lib/types/tools/specs.d.ts +41 -0
  51. package/lib/types/tools/terraform.d.ts +27 -25
  52. package/lib/types/topology.d.ts +232 -0
  53. package/lib/types/types.d.ts +29 -4
  54. package/lib/types/utils/hash.d.ts +15 -5
  55. package/package.json +4 -2
  56. package/lib/types/gates/networking_gate.d.ts +0 -9
  57. package/lib/types/schemas/cost.d.ts +0 -108
  58. package/lib/types/schemas/networking.d.ts +0 -115
  59. package/lib/types/tools/cost.d.ts +0 -16
  60. package/lib/types/tools/networking.d.ts +0 -13
@@ -0,0 +1,111 @@
1
+ /**
2
+ * The D2 renderer itself: source text in, SVG out.
3
+ *
4
+ * ## What this module owns, and what it does not
5
+ *
6
+ * It owns the mechanism — instantiating the WASM build, compiling, rendering,
7
+ * and handing the linear memory back. It knows nothing about topology: the
8
+ * source text it is given could draw anything.
9
+ *
10
+ * That separation is why there are two topology modules beside it
11
+ * (`d2-design.ts` and `d2-inventory.ts`). They generate different source from
12
+ * different inputs, and neither is a mode of the other; putting both in one file
13
+ * made a module whose reader could not tell which rules applied to which
14
+ * picture.
15
+ *
16
+ * ## Why D2 at all
17
+ *
18
+ * A network topology is a nested graph with edges, and every hand-rolled layout
19
+ * for one has to solve two things badly: where a box goes, and where its edges
20
+ * land. D2 solves both, and it is the format's own vocabulary — containers
21
+ * nest, arrows connect, `near:` pins an annotation panel.
22
+ *
23
+ * The cost is real and worth stating: the WASM build is ~21 MB packaged, and
24
+ * the compile step instantiates it once per process (~1.1 s cold, then ~70 ms
25
+ * per diagram). It runs inside a worker thread that D2 owns, so the
26
+ * instantiation does not block this process's event loop; {@link closeD2}
27
+ * terminates that worker, which is the only way to hand the ~600 MB of WASM
28
+ * linear memory back.
29
+ *
30
+ * ## What D2 does and does not carry
31
+ *
32
+ * It carries the PICTURE. It does not carry data: custom `vars` are discarded,
33
+ * an attribute written as a child (`cidr: "10.0.0.0/16"`) becomes a visible
34
+ * second box, and a mistyped attribute or an edge to an undefined node are
35
+ * accepted silently. So nothing is ever read back out of D2 — a topology is
36
+ * derived from its own source and D2 is only where it is drawn. That direction
37
+ * matters: a generator is exact, a parser of pictures is not.
38
+ *
39
+ * @module @huaweidevtools/aishell-dsh-deploy/d2-engine
40
+ */
41
+ /**
42
+ * The D2 themes, light and dark.
43
+ *
44
+ * Theme 5 rather than 0 for light. Theme 0 collapses its accent ramps into one
45
+ * blue-grey: `B`, `AA` and `AB` all resolve to shades of `#EDF0FD`/`#F7F8FE`
46
+ * there, so a diagram styled with three kinds of box draws three boxes in one
47
+ * colour. Theme 5 keeps them apart — blue, violet, pink (measured against the
48
+ * rendered palette, not the docs).
49
+ *
50
+ * 201 rather than 200 for dark, for the same reason and by the same measurement:
51
+ * 200 collapses the same way (`B2` and `AA2` both `#CBA6f7`), 201 keeps a
52
+ * distinguishable blue/violet/teal.
53
+ *
54
+ * Both ids must be given. With no `dark-theme-id` D2 emits NO dark palette at
55
+ * all, and every class would resolve in light colours on a dark ground.
56
+ */
57
+ export declare const LIGHT_THEME_ID = 5;
58
+ export declare const DARK_THEME_ID = 201;
59
+ /** One render in, one render out; the caller owns timing and disposal. */
60
+ export interface RenderResult {
61
+ /** The D2 source that was rendered, so a reader can see what was drawn. */
62
+ readonly source: string;
63
+ /** The SVG, with no XML declaration so it embeds directly in HTML. */
64
+ readonly svg: string;
65
+ }
66
+ /**
67
+ * The `vars` block every generated diagram opens with.
68
+ *
69
+ * The theme ids are written into the diagram rather than passed to `render`, so
70
+ * the generated source is the whole description of what was drawn — a reader
71
+ * feeding it to the D2 CLI gets the same colours.
72
+ *
73
+ * @returns the opening lines of a D2 document.
74
+ */
75
+ export declare function themePreamble(): string[];
76
+ /**
77
+ * Compile D2 source and render it to an SVG.
78
+ *
79
+ * @param source - the D2 source text.
80
+ * @returns the SVG, with no XML declaration.
81
+ * @throws when the source does not compile. That is a defect in the generator
82
+ * rather than in the user's configuration — the generator produced the text —
83
+ * so the caller names the generated fragment in its message.
84
+ */
85
+ export declare function renderD2(source: string): Promise<string>;
86
+ /**
87
+ * Quote a string for a D2 label.
88
+ *
89
+ * @param text - the label.
90
+ * @returns the text inside double quotes, with its own quotes escaped.
91
+ */
92
+ export declare function quote(text: string): string;
93
+ /**
94
+ * The D2 identifier for an address or cloud id.
95
+ *
96
+ * A `.` in a D2 key means "member of the block before it", so an unreplaced one
97
+ * nests the node inside a box named after the part before the dot — inventing a
98
+ * container that does not exist. Every character D2 reserves is replaced by `_`
99
+ * for the same reason.
100
+ *
101
+ * A collision is possible in principle (`a_b.c` and `a.b_c` both map to
102
+ * `a_b_c`). It cannot occur inside one provider namespace, where the separator
103
+ * between resource types and names is always the same `.`, but callers draw
104
+ * from a map keyed by the original id, so a collision would drop an edge rather
105
+ * than misplace it.
106
+ *
107
+ * @param address - a terraform `type.name` address or a cloud resource id.
108
+ * @returns an identifier D2 accepts.
109
+ */
110
+ export declare function d2Id(address: string): string;
111
+ //# sourceMappingURL=d2-engine.d.ts.map
@@ -0,0 +1,54 @@
1
+ /**
2
+ * Drawing an account that already exists.
3
+ *
4
+ * ## What this module is given, and what it is not
5
+ *
6
+ * Its input is `InventoryTopology`: nodes carrying the raw `provider`/`type`
7
+ * the inventory reported, and edges carrying the attribute that established
8
+ * them. Nothing here has been translated into a design vocabulary first, which
9
+ * is why nothing here needs a table of kinds — the picture can contain a
10
+ * service this deployment has never seen.
11
+ *
12
+ * ## Colour
13
+ *
14
+ * A table of types would need a line per service and would be wrong the first
15
+ * time an unfamiliar one appeared. Colouring by provider alone is not enough
16
+ * either: a picture of one VPC and nine security groups then reads as ten of
17
+ * the same thing.
18
+ *
19
+ * So the provider picks the hue and the type picks the lightness step inside it:
20
+ * resources of one service read as a family, and different types inside it stay
21
+ * apart. Both are D2's own theme classes, so the dark palette follows with no
22
+ * JavaScript.
23
+ *
24
+ * The mapping is a hash rather than an assignment, for the same reason: a table
25
+ * that assigned a hue per service would need a new line for every service, and
26
+ * a service missing from it would draw in whatever the fallback happened to be.
27
+ *
28
+ * @module @huaweidevtools/aishell-dsh-deploy/d2-inventory
29
+ */
30
+ import type { InventoryTopology } from './existing-topology.ts';
31
+ import type { RenderResult } from './d2-engine.ts';
32
+ /**
33
+ * The class for one provider/type pair, stable across runs and pictures.
34
+ *
35
+ * @param provider - the service that reported the resource.
36
+ * @param type - that service's own type name.
37
+ * @returns a D2 theme class reference.
38
+ */
39
+ export declare function inventoryClass(provider: string, type: string): string;
40
+ /**
41
+ * Draw an inventory-derived topology.
42
+ *
43
+ * @param topology - the picture derived from the inventory.
44
+ * @returns the D2 source and the SVG it renders to.
45
+ */
46
+ export declare function renderInventoryTopology(topology: InventoryTopology): Promise<RenderResult>;
47
+ /**
48
+ * Generate the D2 source for an inventory-derived topology.
49
+ *
50
+ * @param topology - the picture.
51
+ * @returns D2 source text.
52
+ */
53
+ export declare function inventoryToD2(topology: InventoryTopology): string;
54
+ //# sourceMappingURL=d2-inventory.d.ts.map
@@ -67,4 +67,14 @@ export declare function terraformRoot(): string;
67
67
  export declare function terraformBinDir(): string;
68
68
  /** The terraform provider-plugin cache: `<DSH_HOME>/terraform/plugins`. */
69
69
  export declare function terraformPluginDir(): string;
70
+ /**
71
+ * Where a user-supplied terraform binary path is recorded.
72
+ *
73
+ * `terraform_install` accepts a `terraform_path` the user picked, and every
74
+ * later call has to find that same binary. Passing it per-call was not an
75
+ * option — the path belongs to the deployment, not to one tool invocation — so
76
+ * it is written here and read by `resolveTerraformEnv`, which makes a
77
+ * subsequent `terraform_plan` use the binary `terraform_install` reported.
78
+ */
79
+ export declare function terraformPathRecord(): string;
70
80
  //# sourceMappingURL=data-paths.d.ts.map
@@ -1,12 +1,14 @@
1
1
  /**
2
- * Deployment workspace state (§4.3 .deployment.json).
2
+ * Deployment workspace state: the `.deployment.json` snapshot.
3
3
  *
4
4
  * A deployment directory is identified by the presence of
5
5
  * .deployment.json. The file holds a status snapshot — not an operation
6
- * log. The tools update it on each state change (update_networking /
7
- * update_cost / terraform_apply / terraform_destroy). The model never writes
6
+ * log. The tools update it on each state change (validate_design /
7
+ * price_resources / terraform_plan / terraform_apply / terraform_destroy). The model never writes
8
8
  * this file directly.
9
9
  */
10
+ import type { DesignCheck } from "./gates/design_gate.js";
11
+ import type { DestroyRecord, PlanRecord } from "./gates/plan_gate.js";
10
12
  export declare const DEPLOYMENT_STATE_FILE = ".deployment.json";
11
13
  export interface DeploymentSnapshot {
12
14
  created_at: string;
@@ -17,7 +19,27 @@ export interface DeploymentSnapshot {
17
19
  account_id: string;
18
20
  };
19
21
  status: {
20
- networking_written: boolean;
22
+ /**
23
+ * The last `validate_design` run: what it checked, and whether it passed.
24
+ *
25
+ * A digest rather than a boolean, because the question the apply gate asks
26
+ * is "was THIS configuration checked" — and a design edited after it was
27
+ * checked is not a checked one. Absent until the first run.
28
+ */
29
+ design_check?: DesignCheck;
30
+ /**
31
+ * The last `terraform_plan`: the digest of the configuration it planned,
32
+ * and what it found. `terraform_apply` runs THAT plan file and refuses when
33
+ * this digest no longer matches — terraform itself will apply a saved plan
34
+ * whose configuration has changed, so the record is what ties the two.
35
+ */
36
+ plan_check?: PlanRecord;
37
+ /**
38
+ * The last `terraform_plan({ destroy: true })`: the targets it previewed and
39
+ * the configuration it computed them from. `terraform_destroy` applies that
40
+ * saved plan and refuses when this record does not name the same targets.
41
+ */
42
+ destroy_check?: DestroyRecord;
21
43
  cost_written: boolean;
22
44
  applied: boolean;
23
45
  destroyed: boolean;
@@ -27,6 +49,20 @@ export interface DeploymentSnapshot {
27
49
  }
28
50
  /** Check whether a directory is a deployment (has .deployment.json). */
29
51
  export declare function isDeploymentDir(dir: string): Promise<boolean>;
52
+ /**
53
+ * Read the deployment snapshot, when the directory has one.
54
+ *
55
+ * `undefined` rather than a throw: a directory that is not a deployment
56
+ * workspace is a normal thing to point at (the user named one directly, or
57
+ * `create_deployment` was skipped), and the tools that write into the
58
+ * workspace work there too. Each caller decides whether a missing snapshot is
59
+ * interesting — the design gate treats it as "never checked", `updateSnapshot`
60
+ * as "nothing to update".
61
+ *
62
+ * @param dir - the directory that may hold a deployment.
63
+ * @returns the snapshot, or `undefined`.
64
+ */
65
+ export declare function readSnapshot(dir: string): Promise<DeploymentSnapshot | undefined>;
30
66
  /** Create a deployment directory + initial .deployment.json. Refuse if non-empty. */
31
67
  export declare function ensureDeployment(dir: string): Promise<DeploymentSnapshot>;
32
68
  /** Update the status snapshot (called by other modules after state changes). */
@@ -35,8 +71,8 @@ export declare function updateSnapshot(dir: string, patch: Partial<DeploymentSna
35
71
  }): Promise<void>;
36
72
  /**
37
73
  * Backfill the account field in .deployment.json if it's empty and the
38
- * server is now authenticated (§4.3: "后续 auth 后 server 操作该 deployment
39
- * 时补写").
74
+ * server is now authenticated, so a workspace created before the first
75
+ * sign-in still ends up naming the account it belongs to.
40
76
  *
41
77
  * Called by runTerraform after resolveTerraformEnv succeeds. The account
42
78
  * identity was resolved at auth time (GET /v3/projects → domain_id + name)
@@ -55,15 +91,56 @@ export declare function backfillAccount(dir: string, account: {
55
91
  account_id: string;
56
92
  }): Promise<void>;
57
93
  /**
58
- * Count resources recorded in terraform.tfstate (0 = clean / never applied).
94
+ * Count the resources this deployment manages, by asking terraform.
95
+ *
96
+ * ## Why not read `terraform.tfstate`
97
+ *
98
+ * A deployment may configure a backend (`backend "obs"`, `backend "s3"`), in
99
+ * which case terraform writes state to the bucket and leaves no
100
+ * `terraform.tfstate` in the workspace. Reading that file as a proxy for "does
101
+ * this deployment own anything" then answers 0 for a deployment that owns
102
+ * everything — and both callers of this function act on the answer:
103
+ * `terraform_destroy` refuses ("nothing to destroy"), and `delete_deployment`
104
+ * proceeds to delete the workspace while the cloud resources stay up and
105
+ * unmanaged.
106
+ *
107
+ * So the count is asked of the backend that is actually configured. The
108
+ * subprocess is injected rather than imported: this module is the snapshot
109
+ * store, and reaching into the terraform runner would make the import graph
110
+ * cyclic — the runner already reads this module to backfill the account.
111
+ *
112
+ * @param dir - the deployment workspace directory.
113
+ * @param listState - runs `terraform state list` and returns its stdout and
114
+ * exit code; injected so this module stays testable without a binary.
115
+ * @returns how many resources the configured backend holds.
116
+ */
117
+ export declare function stateRecordedResourceCount(dir: string, listState: (dir: string, args: string[]) => Promise<{
118
+ exitCode: number;
119
+ stdout: string;
120
+ }>): Promise<number>;
121
+ /**
122
+ * Forget what was planned and previewed, after the run those records authorised.
123
+ *
124
+ * ## Why this is not housekeeping
125
+ *
126
+ * A saved plan is a one-shot artifact. terraform refuses to apply the same plan
127
+ * file twice — "the given plan file can no longer be applied because the state
128
+ * was changed by another operation after the plan was created" (verified) —
129
+ * while every record this module keeps still matches, because a successful
130
+ * apply does not change the `.tf`. So a second `terraform_apply` would pass all
131
+ * the gates, run, and fail on terraform's own error, which names neither the
132
+ * gate nor the remedy.
133
+ *
134
+ * Clearing the records moves that case onto the gate that has the remedy: with
135
+ * no `plan_check`, `assertPlanApproved` says "call terraform_plan first", which
136
+ * is exactly what the next deployment change needs anyway.
137
+ *
138
+ * The destroy record goes with it for the same reason: a teardown previewed
139
+ * before an apply describes state that no longer exists.
59
140
  *
60
- * This is the count RECORDED in the state file, NOT the live count on the
61
- * cloud — tfstate may be stale if resources were changed outside terraform.
62
- * For the live count, run terraform_refresh first. Used by delete_deployment
63
- * and terraform_destroy to guard against destroying/emptying a deployment
64
- * that still has recorded resources.
141
+ * @param dir - the deployment workspace directory.
65
142
  */
66
- export declare function stateRecordedResourceCount(dir: string): Promise<number>;
143
+ export declare function clearPlanRecords(dir: string): Promise<void>;
67
144
  /** Remove the deployment directory. */
68
145
  export declare function removeDeploymentDir(dir: string): Promise<void>;
69
146
  //# sourceMappingURL=deployment-state.d.ts.map
@@ -0,0 +1,154 @@
1
+ /**
2
+ * The topology of an account that already exists, derived from what the
3
+ * inventory reports.
4
+ *
5
+ * ## What this module knows, and why it is not a table of services
6
+ *
7
+ * The inventory returns resources as `{provider, type, id, name, properties}`.
8
+ * Two different questions are answered from `properties`, and they are not the
9
+ * same kind of question:
10
+ *
11
+ * - **Association.** When one resource's property holds another resource's
12
+ * id, the two are related. That rule needs no vocabulary at all: an id is
13
+ * an id, whatever the service. Associations are drawn as edges.
14
+ * - **Location.** Which resource a box is drawn INSIDE is a fact about the
15
+ * network picture, not about the service that reported it. A network
16
+ * picture is made of networks and their subdivisions — that is what the
17
+ * domain is, in every cloud — so the location vocabulary is those nouns and
18
+ * nothing else: `vpc`, `subnet`.
19
+ *
20
+ * That vocabulary is two words. It is not a per-service table that grows with
21
+ * every service, and it does not name a single service: a service this
22
+ * deployment has never seen gets placed correctly the first time it appears, as
23
+ * long as it says where it lives, because saying where it lives is what makes
24
+ * it placeable.
25
+ *
26
+ * ## Why containment is not derived from the graph
27
+ *
28
+ * Reference counts cannot answer "what contains what". A rule built on them —
29
+ * a container is a type that receives references and makes none back — fails
30
+ * three ways, every one of them observable on a real account:
31
+ *
32
+ * 1. **It cannot nest three levels.** A server names both its subnet and its
33
+ * VPC; the subnet names the VPC. Each of those is a reference into a
34
+ * container, the deeper placement is never considered, and the server ends
35
+ * up inside the VPC with its subnet beside it — the one arrangement that is
36
+ * wrong.
37
+ * 2. **It makes a security group a container.** A security group receives
38
+ * references and makes none back, which satisfies the rule exactly. A
39
+ * listener that names only a security group lands inside its box.
40
+ * 3. **It depends on a complete graph, and the inventory is not complete.**
41
+ * RMS does not report subnets at all, so the counts a rule needs are
42
+ * missing the very edges that would say "this is a subnet of that VPC".
43
+ *
44
+ * Containment therefore comes from the attribute's own name, which is the
45
+ * provider stating what the relationship is. `vpcId` says "this lives in that
46
+ * VPC"; `securityGroupId` says "this is admitted by that group" — both are
47
+ * references, only one is a location.
48
+ *
49
+ * ## What it deliberately does not do
50
+ *
51
+ * It does not decide that a resource is unimportant. Every resource the
52
+ * inventory returned becomes a node. A diagram that hides things needs a
53
+ * reason to hide them, and a rule for "important" is a table by another name.
54
+ *
55
+ * @module @huaweidevtools/aishell-dsh-deploy/existing-topology
56
+ */
57
+ /** One resource as the inventory reports it. */
58
+ export interface InventoryResource {
59
+ readonly id: string;
60
+ /** The service, e.g. `vpc`, `ecs`, `rds`. */
61
+ readonly provider: string;
62
+ /** The service's own type name, e.g. `vpcs`, `cloudservers`, `securityGroups`. */
63
+ readonly type: string;
64
+ readonly name?: string;
65
+ readonly region?: string;
66
+ readonly properties?: Readonly<Record<string, unknown>>;
67
+ }
68
+ /** One node in the derived picture. */
69
+ export interface InventoryNode {
70
+ /** Stable identity: the cloud resource id. */
71
+ readonly id: string;
72
+ readonly provider: string;
73
+ readonly type: string;
74
+ readonly label: string;
75
+ /** Facts worth showing on the box, already chosen. */
76
+ readonly facts: readonly {
77
+ readonly key: string;
78
+ readonly value: string;
79
+ }[];
80
+ /** The container this node sits in, when one was found. */
81
+ readonly parent: string | undefined;
82
+ /** Every container above this node, nearest first. */
83
+ readonly ancestors: readonly string[];
84
+ readonly children: readonly InventoryNode[];
85
+ }
86
+ /** One relationship between two resources. */
87
+ export interface InventoryEdge {
88
+ readonly from: string;
89
+ readonly to: string;
90
+ /** The attribute that establishes it, e.g. `vnic.vpcId`. */
91
+ readonly attribute: string;
92
+ /**
93
+ * Whether this attribute names a container rather than a peer.
94
+ *
95
+ * Both are drawn; the distinction decides nesting versus an arrow, and is
96
+ * carried rather than acted on here so a reader can see why a resource was
97
+ * placed where it was.
98
+ */
99
+ readonly contains: boolean;
100
+ }
101
+ /** The whole derived picture. */
102
+ export interface InventoryTopology {
103
+ readonly roots: readonly InventoryNode[];
104
+ readonly nodes: readonly InventoryNode[];
105
+ readonly edges: readonly InventoryEdge[];
106
+ /** Resources that appeared in more than one provider/type bucket. */
107
+ readonly duplicates: readonly string[];
108
+ }
109
+ /**
110
+ * Every scalar the properties contain, keyed by its dotted path.
111
+ *
112
+ * Nested objects and arrays are flattened because the inventory nests ids
113
+ * arbitrarily deep (`vnic.vpcId`, `bandwidth.id`,
114
+ * `security_group_rules[].remote_group_id`), and a rule that only looked at the
115
+ * top level would miss most of the relationships.
116
+ *
117
+ * A JSON-encoded value is also opened, because the inventory sometimes ships one
118
+ * as a string. RDS is the case that was measured: it reports `vpcId` as
119
+ * `"[\"73e76381-…\"]"` and `networkId` as its subnet — a real reference, present
120
+ * and correct, that a plain string comparison never matches. Left closed, the
121
+ * RDS instance floats at the root of the picture with its VPC in plain sight in
122
+ * its own properties.
123
+ *
124
+ * @param value - any property value.
125
+ * @returns path → scalar, for every leaf.
126
+ */
127
+ export declare function flattenProperties(value: unknown): Map<string, string>;
128
+ /**
129
+ * How specific a location an attribute names, 0 when it names none.
130
+ *
131
+ * The tail of the path is what counts: `vnic.vpcId` and `metadata.vpcId` both
132
+ * end in a noun describing the container. Everything before the last dot is the
133
+ * service's own nesting and says nothing about which container this is.
134
+ *
135
+ * The `id`/`uid`/`uuid` suffix is stripped rather than required to be present,
136
+ * because the provider writes all three (`subnet_id`, `subnetId`,
137
+ * `virsubnet_id`) and a rule that demanded one spelling would miss the others.
138
+ * A plural suffix is stripped too: `elb_virsubnet_ids` holds several subnets,
139
+ * and whether the attribute holds one id or a list does not change what it
140
+ * names. Suffix matching, not equality, is what makes `virsubnet` and
141
+ * `subnetwork` land on the same noun.
142
+ *
143
+ * @param attribute - a dotted property path.
144
+ * @returns the rank of the location it names, or 0 for a plain association.
145
+ */
146
+ export declare function locationRank(attribute: string): number;
147
+ /**
148
+ * Derive the picture from what the inventory reported.
149
+ *
150
+ * @param resources - every resource the inventory returned.
151
+ * @returns nodes, edges, and the nesting derived from both.
152
+ */
153
+ export declare function deriveInventoryTopology(resources: readonly InventoryResource[]): InventoryTopology;
154
+ //# sourceMappingURL=existing-topology.d.ts.map
@@ -0,0 +1,100 @@
1
+ /**
2
+ * Cloud resources that already exist, as the diagram shows them.
3
+ *
4
+ * ## Why these arrive as a parameter
5
+ *
6
+ * The design stage answers "what should the network be". In an account that
7
+ * already has a VPC, that question is partly "what can be reused", and a
8
+ * diagram drawn only from the `.tf` answers a different question: it shows what
9
+ * will be created and says nothing about what is already there.
10
+ *
11
+ * The caller supplies them because it is the only party that knows which of the
12
+ * account's resources the user is designing AROUND. `list_existing_resources`
13
+ * returns everything in the account — usually far more than the design is
14
+ * about — and picking the relevant subset is a judgement, not a query. An
15
+ * automatic "match by name or CIDR" rule would be a guess, and a diagram that
16
+ * guesses is worse than one that omits.
17
+ *
18
+ * ## Why they are not given terraform addresses
19
+ *
20
+ * These are not managed by this deployment. They have a cloud id and a name,
21
+ * and no `type.name` address — that identity belongs to whoever's terraform
22
+ * manages them, not to this one. They are marked instead, so a reader can tell
23
+ * at a glance which boxes this deployment will create and which it will use.
24
+ *
25
+ * @module @huaweidevtools/aishell-dsh-deploy/existing
26
+ */
27
+ import { z } from 'zod';
28
+ /**
29
+ * The shape a caller sends for one existing resource.
30
+ *
31
+ * `type` is accepted in either spelling — the terraform type
32
+ * (`huaweicloud_vpc`) or RMS's short name (`vpc`) — because both are what a
33
+ * caller has to hand. RMS is the likelier source: it is the tool that lists
34
+ * what exists, and it answers with short names.
35
+ *
36
+ * `parent` is the containing resource's ID, which is how a caller says "this
37
+ * ECS is in that subnet". It is optional: a caller that does not know the
38
+ * placement still gets the box, at the root.
39
+ */
40
+ export declare const ExistingResourceSchema: z.ZodObject<{
41
+ id: z.ZodString;
42
+ type: z.ZodString;
43
+ provider: z.ZodOptional<z.ZodString>;
44
+ properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
45
+ name: z.ZodOptional<z.ZodString>;
46
+ parent: z.ZodOptional<z.ZodString>;
47
+ cidr: z.ZodOptional<z.ZodString>;
48
+ region: z.ZodOptional<z.ZodString>;
49
+ flavor: z.ZodOptional<z.ZodString>;
50
+ address: z.ZodOptional<z.ZodString>;
51
+ }, z.core.$strip>;
52
+ /** One existing resource, as the caller described it. */
53
+ export type ExistingResource = z.infer<typeof ExistingResourceSchema>;
54
+ /** The node kind an existing resource takes, from either type spelling. */
55
+ export type ExistingKind = 'vpc' | 'subnet' | 'security-group' | 'security-group-rule' | 'gateway' | 'load-balancer' | 'compute' | 'database';
56
+ /**
57
+ * What a resource is, as far as the topology is concerned — or nothing.
58
+ *
59
+ * The seven kinds that can appear are the vocabulary a network design is
60
+ * written in. Everything else is not "an unknown kind of box": it is a
61
+ * resource the picture is not about, and drawing it would put a key pair or an
62
+ * alarm rule next to a subnet as if the reader should compare them.
63
+ *
64
+ * So the lookup answers `undefined` for those, and the caller reports them
65
+ * instead of inventing a shape. That is the difference between "this diagram
66
+ * shows the network" and "this diagram shows whatever the file contained".
67
+ */
68
+ export type TopologyKind = ExistingKind;
69
+ /**
70
+ * What one configured resource is.
71
+ *
72
+ * This answers for a `.tf` block, whose type is the provider's own spelling. An
73
+ * account's resources do not come through here: the inventory already knows
74
+ * what each one is, and a table of its vocabulary would grow with every service
75
+ * — see `existing-topology.ts` for how that case is derived instead.
76
+ *
77
+ * @param type - a terraform type (`huaweicloud_vpc`) or the short name the
78
+ * provider's own docs use (`vpc`).
79
+ * @returns the node kind, or `undefined` when the picture has none for it.
80
+ */
81
+ export declare function kindOfExisting(type: string): ExistingKind | undefined;
82
+ /**
83
+ * What one described resource is.
84
+ *
85
+ * `type` is resolved on its own, which is the whole answer for a caller that
86
+ * sent a terraform type. A caller that copied an RMS `type` has a plural
87
+ * vocabulary ("vpcs", "cloudservers") that says nothing about what the resource
88
+ * IS — and `instances` is both a database and an API gateway, depending on the
89
+ * provider. So when `provider` is present it is used to disambiguate, and when
90
+ * the pair resolves to nothing the answer is `undefined`: the resource is real
91
+ * but this picture has no box for it.
92
+ *
93
+ * @param resource - the described resource.
94
+ * @returns the kind, or `undefined` when the picture has none for it.
95
+ */
96
+ export declare function kindOfResource(resource: {
97
+ readonly type: string;
98
+ readonly provider?: string | undefined;
99
+ }): ExistingKind | undefined;
100
+ //# sourceMappingURL=existing.d.ts.map
@@ -1,24 +1,46 @@
1
1
  /**
2
- * cost_gate.ts — cost.json existence + tf_hash state machine (§6.3 门 2+3).
2
+ * The gate `terraform_apply` runs on the cost record.
3
3
  *
4
- * The tf_hash logic:
5
- * - cost.json written BEFORE .tf, so tf_hash is null on write
6
- * - null → allow (first time / last apply failed); fill hash after success
7
- * - non-null → recompute current .tf SHA256, compare; mismatch rejects
4
+ * ## Two questions, both about the record's honesty
8
5
  *
9
- * "Fill after success, not before" (§4.1): apply failure doesn't fill,
10
- * so retry after a bug fix doesn't demand a pointless cost recompute.
6
+ * **Was anything priced?** `cost.json` exists and carries either a quote or a
7
+ * statement that the plan holds nothing to charge for. A deployment with
8
+ * neither has no approved cost, and applying it spends money nobody agreed to.
9
+ *
10
+ * An empty quote list alone is not an answer: a network of VPCs, subnets and
11
+ * security groups has no items and costs nothing, while a deployment of
12
+ * unpriced databases has no items and costs something nobody established. The
13
+ * record's `nothing_billable` flag is what separates them.
14
+ *
15
+ * **Is the record current?** The record stores the digest of the configuration
16
+ * it was priced against. This gate recomputes that digest from the files on
17
+ * disk and refuses when they differ. A price is a property of the
18
+ * configuration: edit a flavour, an image or a resource count and the old total
19
+ * describes something that will not be built.
20
+ *
21
+ * ## What the record is now
22
+ *
23
+ * `cost.json` is written by `price_resources` from the BSS rating API, so every
24
+ * figure in it came from an inquiry. It is not a form the model fills in — the
25
+ * tool that writes it is the only writer, which is why there is no separate
26
+ * "did you cost it" step to enforce. This gate guards the two ways a correct
27
+ * record can still be wrong at apply time: absent, and stale.
28
+ *
29
+ * ## Why it does not re-price
30
+ *
31
+ * Re-pricing here would make apply depend on a live billing call — a rate limit
32
+ * or a catalogue hiccup would block a deployment that was fully reviewed five
33
+ * minutes earlier. The digest answers "was this configuration priced", which is
34
+ * the question that matters; a price that has moved since is a difference the
35
+ * user accepted when they approved that number.
36
+ *
37
+ * @module @huaweidevtools/aishell-dsh-deploy/gates/cost_gate
11
38
  */
12
- import type { Cost } from "../schemas/cost.js";
13
- export declare function loadCost(dir: string): Promise<Cost>;
14
- export declare function costJsonExists(dir: string): Promise<boolean>;
15
39
  /**
16
- * Run the cost gate. Returns the cost.json (with its tf_hash) so the
17
- * caller can fill it after a successful apply.
40
+ * Refuse an apply whose cost record is absent, empty, or stale.
18
41
  *
19
- * @throws Error if cost.json missing or tf_hash mismatch
42
+ * @param dir - the deployment workspace directory.
43
+ * @throws when the record is unusable.
20
44
  */
21
- export declare function runCostGate(dir: string): Promise<Cost>;
22
- /** Fill tf_hash in cost.json after a successful apply (§6.3). */
23
- export declare function fillTfHash(dir: string): Promise<void>;
45
+ export declare function runCostGate(dir: string, hashConfiguration?: (directory: string) => Promise<string>): Promise<void>;
24
46
  //# sourceMappingURL=cost_gate.d.ts.map