Refresh HiveGrid Cloud reference snapshot
This commit is contained in:
1 parent
5e99e14772
commit
7f88026f79
5955 files changed
+1177325
-188362
No files matched your search
@@ -0,0 +1,341 @@
|
||||
#!/usr/bin/env node
|
||||
|
||||
import { readFile, writeFile, mkdir } from "node:fs/promises";
|
||||
import { dirname, resolve } from "node:path";
|
||||
|
||||
const EXTERNAL_SCOPES = Object.freeze(["adresse-extern", "archiv-extern", "termin-extern", "vorgang-extern", "aktivitaet-extern"]);
|
||||
|
||||
const CAPABILITY_BY_TAG = Object.freeze({
|
||||
Adresse: "address",
|
||||
Aktivitaet: "activity",
|
||||
Aktivitaetenverwaltung: "activity",
|
||||
ArchivExternal: "archive",
|
||||
Monteursteuerung: "schedule",
|
||||
Projekt: "project",
|
||||
Projektampel: "project",
|
||||
Termin: "schedule",
|
||||
VorgangAnzeige: "project",
|
||||
VorgangInfo: "project",
|
||||
});
|
||||
|
||||
const MUTATION_PATH_PATTERN = /\/(?:Add|Delete|Import|Publish|Remove|Reset|Save)[^/]*$/u;
|
||||
const SUPPORTED_METHODS = new Set(["delete", "get", "post", "put", "patch"]);
|
||||
const CONTRACT_OUTPUT = "packages/integrations/src/kwp/contract/kwp-scoped-openapi.json";
|
||||
const CATALOG_OUTPUT = "packages/integrations/src/kwp/contract/catalog.generated.ts";
|
||||
const SCOPE_DOC_OUTPUT = "docs/integrations/KWP-API-SCOPE.md";
|
||||
|
||||
const [inputArg, contractOutputArg, scopeDocOutputArg, catalogOutputArg] = process.argv.slice(2);
|
||||
if (!inputArg) {
|
||||
process.stderr.write("Usage: node scripts/generate-kwp-scoped-contract.mjs <tenant-openapi.json> [contract-output] [scope-doc-output] [catalog-output]\n");
|
||||
process.exitCode = 1;
|
||||
} else {
|
||||
await generate({
|
||||
inputPath: resolve(inputArg),
|
||||
contractOutputPath: resolve(contractOutputArg ?? CONTRACT_OUTPUT),
|
||||
scopeDocOutputPath: resolve(scopeDocOutputArg ?? SCOPE_DOC_OUTPUT),
|
||||
catalogOutputPath: resolve(catalogOutputArg ?? CATALOG_OUTPUT),
|
||||
});
|
||||
}
|
||||
|
||||
async function generate({ inputPath, contractOutputPath, scopeDocOutputPath, catalogOutputPath }) {
|
||||
const source = JSON.parse(await readFile(inputPath, "utf8"));
|
||||
assertOpenApi(source);
|
||||
|
||||
const allOperations = listOperations(source);
|
||||
const scopedOperations = allOperations
|
||||
.filter((operation) => operation.scopes.some((scope) => EXTERNAL_SCOPES.includes(scope)))
|
||||
.map((operation) => ({
|
||||
...operation,
|
||||
capability: requireCapability(operation.tag),
|
||||
mode: MUTATION_PATH_PATTERN.test(operation.path) ? "mutation" : "read",
|
||||
}))
|
||||
.sort(compareOperations);
|
||||
|
||||
assertInventory(allOperations, scopedOperations);
|
||||
const duplicatePaths = new Set(
|
||||
scopedOperations
|
||||
.filter((operation, index, operations) => operations.some((candidate, candidateIndex) => candidateIndex !== index && candidate.path === operation.path))
|
||||
.map((operation) => operation.path)
|
||||
);
|
||||
|
||||
const paths = {};
|
||||
for (const operation of scopedOperations) {
|
||||
const operationId = buildOperationId(operation, duplicatePaths);
|
||||
const operationContract = stripDocumentationMetadata(structuredClone(operation.contract));
|
||||
operationContract.operationId = operationId;
|
||||
operationContract["x-hivegrid-capability"] = operation.capability;
|
||||
operationContract["x-hivegrid-mode"] = operation.mode;
|
||||
paths[operation.path] ??= {};
|
||||
paths[operation.path][operation.method] = operationContract;
|
||||
}
|
||||
|
||||
const schemaNames = collectReferencedSchemaNames(paths, source.components.schemas);
|
||||
const schemas = Object.fromEntries(
|
||||
[...schemaNames].sort((left, right) => left.localeCompare(right)).map((name) => [name, stripDocumentationMetadata(source.components.schemas[name])])
|
||||
);
|
||||
const inventory = {
|
||||
sourceOperationCount: allOperations.length,
|
||||
scopedOperationCount: scopedOperations.length,
|
||||
readOperationCount: scopedOperations.filter((operation) => operation.mode === "read").length,
|
||||
mutationOperationCount: scopedOperations.filter((operation) => operation.mode === "mutation").length,
|
||||
excludedOperationCount: allOperations.length - scopedOperations.length,
|
||||
externalScopes: EXTERNAL_SCOPES,
|
||||
capabilities: Object.fromEntries(
|
||||
[...new Set(scopedOperations.map((operation) => operation.capability))].sort().map((capability) => [
|
||||
capability,
|
||||
{
|
||||
total: scopedOperations.filter((operation) => operation.capability === capability).length,
|
||||
read: scopedOperations.filter((operation) => operation.capability === capability && operation.mode === "read").length,
|
||||
mutation: scopedOperations.filter((operation) => operation.capability === capability && operation.mode === "mutation").length,
|
||||
},
|
||||
])
|
||||
),
|
||||
};
|
||||
const scopedContract = {
|
||||
openapi: source.openapi,
|
||||
info: {
|
||||
title: "KWP Api, licensed scope",
|
||||
version: source.info.version,
|
||||
},
|
||||
paths: sortObject(paths),
|
||||
components: { schemas },
|
||||
"x-hivegrid-inventory": inventory,
|
||||
};
|
||||
|
||||
await mkdir(dirname(contractOutputPath), { recursive: true });
|
||||
await writeFile(contractOutputPath, `${JSON.stringify(scopedContract, null, 2)}\n`);
|
||||
await mkdir(dirname(scopeDocOutputPath), { recursive: true });
|
||||
await writeFile(scopeDocOutputPath, renderScopeDocument(scopedOperations, inventory, inputPath));
|
||||
await mkdir(dirname(catalogOutputPath), { recursive: true });
|
||||
await writeFile(catalogOutputPath, renderTypeScriptCatalog(scopedOperations, duplicatePaths, inventory));
|
||||
process.stdout.write(
|
||||
`Generated ${scopedOperations.length} KWP scoped operations (${inventory.readOperationCount} read, ${inventory.mutationOperationCount} mutation).\n`
|
||||
);
|
||||
}
|
||||
|
||||
function assertOpenApi(value) {
|
||||
if (
|
||||
!value ||
|
||||
typeof value !== "object" ||
|
||||
typeof value.openapi !== "string" ||
|
||||
!value.info ||
|
||||
typeof value.info.version !== "string" ||
|
||||
!value.paths ||
|
||||
typeof value.paths !== "object" ||
|
||||
!value.components?.schemas ||
|
||||
typeof value.components.schemas !== "object"
|
||||
) {
|
||||
throw new Error("The input is not the expected KWP OpenAPI document");
|
||||
}
|
||||
}
|
||||
|
||||
function listOperations(source) {
|
||||
const operations = [];
|
||||
for (const [path, pathItem] of Object.entries(source.paths)) {
|
||||
for (const [method, contract] of Object.entries(pathItem)) {
|
||||
if (!SUPPORTED_METHODS.has(method) || !contract || typeof contract !== "object") continue;
|
||||
const tag = Array.isArray(contract.tags) ? contract.tags[0] : undefined;
|
||||
if (typeof tag !== "string" || tag.length === 0) {
|
||||
throw new Error(`KWP operation ${method.toUpperCase()} ${path} has no tag`);
|
||||
}
|
||||
operations.push({
|
||||
method,
|
||||
path,
|
||||
tag,
|
||||
summary: typeof contract.summary === "string" ? contract.summary : "",
|
||||
scopes: readSecurityScopes(contract.security),
|
||||
contract,
|
||||
});
|
||||
}
|
||||
}
|
||||
return operations;
|
||||
}
|
||||
|
||||
function readSecurityScopes(security) {
|
||||
if (!Array.isArray(security)) return [];
|
||||
return [
|
||||
...new Set(
|
||||
security.flatMap((entry) =>
|
||||
entry && typeof entry === "object" && Array.isArray(entry.oauth2) ? entry.oauth2.filter((scope) => typeof scope === "string") : []
|
||||
)
|
||||
),
|
||||
];
|
||||
}
|
||||
|
||||
function requireCapability(tag) {
|
||||
const capability = CAPABILITY_BY_TAG[tag];
|
||||
if (!capability) throw new Error(`Scoped KWP tag ${tag} is not assigned to a capability`);
|
||||
return capability;
|
||||
}
|
||||
|
||||
function assertInventory(allOperations, scopedOperations) {
|
||||
const readCount = scopedOperations.filter((operation) => operation.mode === "read").length;
|
||||
const mutationCount = scopedOperations.length - readCount;
|
||||
if (allOperations.length !== 554 || scopedOperations.length !== 113 || readCount !== 77 || mutationCount !== 36) {
|
||||
throw new Error(`KWP inventory drifted: total=${allOperations.length}, scoped=${scopedOperations.length}, read=${readCount}, mutation=${mutationCount}`);
|
||||
}
|
||||
}
|
||||
|
||||
function buildOperationId(operation, duplicatePaths) {
|
||||
const base = `${toIdentifier(operation.tag, false)}${toIdentifier(operation.path.split("/").at(-1), true)}`;
|
||||
return duplicatePaths.has(operation.path) ? `${base}${toIdentifier(operation.method, true)}` : base;
|
||||
}
|
||||
|
||||
function toIdentifier(value, upperFirst) {
|
||||
const words = String(value ?? "").match(/[A-Za-z0-9]+/gu) ?? [];
|
||||
const joined = words
|
||||
.map((word, index) => {
|
||||
const normalized = word[0].toUpperCase() + word.slice(1);
|
||||
if (index === 0 && !upperFirst) return normalized[0].toLowerCase() + normalized.slice(1);
|
||||
return normalized;
|
||||
})
|
||||
.join("");
|
||||
if (!joined) throw new Error(`Cannot derive an operation identifier from ${value}`);
|
||||
return joined;
|
||||
}
|
||||
|
||||
function collectReferencedSchemaNames(value, allSchemas) {
|
||||
const found = new Set();
|
||||
const pending = [...findRefs(value)];
|
||||
while (pending.length > 0) {
|
||||
const ref = pending.pop();
|
||||
const prefix = "#/components/schemas/";
|
||||
if (!ref.startsWith(prefix)) {
|
||||
throw new Error(`Unsupported KWP contract reference ${ref}`);
|
||||
}
|
||||
const name = decodeURIComponent(ref.slice(prefix.length));
|
||||
if (found.has(name)) continue;
|
||||
const schema = allSchemas[name];
|
||||
if (!schema) throw new Error(`Missing KWP schema ${name}`);
|
||||
found.add(name);
|
||||
pending.push(...findRefs(schema));
|
||||
}
|
||||
return found;
|
||||
}
|
||||
|
||||
function findRefs(value) {
|
||||
if (Array.isArray(value)) return value.flatMap(findRefs);
|
||||
if (!value || typeof value !== "object") return [];
|
||||
return Object.entries(value).flatMap(([key, nested]) => (key === "$ref" && typeof nested === "string" ? [nested] : findRefs(nested)));
|
||||
}
|
||||
|
||||
function stripDocumentationMetadata(value) {
|
||||
if (Array.isArray(value)) return value.map(stripDocumentationMetadata);
|
||||
if (!value || typeof value !== "object") return value;
|
||||
return Object.fromEntries(
|
||||
Object.entries(value)
|
||||
.filter(([key]) => key !== "description")
|
||||
.map(([key, nested]) => [key, stripDocumentationMetadata(nested)])
|
||||
);
|
||||
}
|
||||
|
||||
function compareOperations(left, right) {
|
||||
return (
|
||||
left.capability.localeCompare(right.capability) ||
|
||||
left.tag.localeCompare(right.tag) ||
|
||||
left.path.localeCompare(right.path) ||
|
||||
left.method.localeCompare(right.method)
|
||||
);
|
||||
}
|
||||
|
||||
function sortObject(value) {
|
||||
return Object.fromEntries(
|
||||
Object.entries(value)
|
||||
.sort(([left], [right]) => left.localeCompare(right))
|
||||
.map(([key, nested]) => [key, nested && typeof nested === "object" && !Array.isArray(nested) ? sortObject(nested) : nested])
|
||||
);
|
||||
}
|
||||
|
||||
function renderScopeDocument(operations, inventory) {
|
||||
const capabilityRows = Object.entries(inventory.capabilities)
|
||||
.map(([capability, counts]) => `| ${capability} | ${counts.total} | ${counts.read} | ${counts.mutation} |`)
|
||||
.join("\n");
|
||||
const operationRows = operations
|
||||
.map((operation) => {
|
||||
const id = buildOperationId(
|
||||
operation,
|
||||
new Set(
|
||||
operations
|
||||
.filter((candidate, index, all) => all.some((other, otherIndex) => otherIndex !== index && other.path === candidate.path))
|
||||
.map((candidate) => candidate.path)
|
||||
)
|
||||
);
|
||||
return `| \`${id}\` | ${operation.capability} | ${operation.mode} | \`${operation.method.toUpperCase()}\` | \`${operation.path}\` | ${escapeTableText(operation.summary)} |`;
|
||||
})
|
||||
.join("\n");
|
||||
|
||||
return `# KWP API: lizenzierter HiveGrid-Scope
|
||||
|
||||
> Generiert aus der am 2026-07-24 secretsicher gelesenen Tenant-OpenAPI. Die kundenspezifische
|
||||
> Roh-Spezifikation, Server-URL und Credentials werden nicht eingecheckt.
|
||||
|
||||
## Inventur
|
||||
|
||||
- OpenAPI-Operationen gesamt: **${inventory.sourceOperationCount}**
|
||||
- Über die fünf HiveGrid-\`*-extern\`-Scopes erreichbar: **${inventory.scopedOperationCount}**
|
||||
- Semantisch lesend und runtime-allowlisted: **${inventory.readOperationCount}**
|
||||
- Mutierend, nur Contract/Fixture und runtime-gesperrt: **${inventory.mutationOperationCount}**
|
||||
- Außerhalb des lizenzierten HiveGrid-Scopes: **${inventory.excludedOperationCount}**
|
||||
|
||||
| Capability | Gesamt | Read | Mutation |
|
||||
|---|---:|---:|---:|
|
||||
${capabilityRows}
|
||||
|
||||
Die OpenAPI-Security-Arrays nennen mehrere alternative KWP-Produkte und die fünf externen Scopes, obwohl
|
||||
die OAuth-Flow-Scope-Liste diese externen Namen nicht aufführt. HiveGrid klassifiziert eine Operation nur
|
||||
dann als scoped, wenn mindestens einer der fünf tatsächlich angeforderten externen Scopes am Endpoint steht.
|
||||
|
||||
## Sicherheitsvertrag
|
||||
|
||||
- Fachcode übergibt nur eine feste Operation-ID plus deren typisierten Input, niemals URL, Pfad, Token,
|
||||
Mandant oder Kundenkürzel.
|
||||
- \`Search\`, \`Load\`, \`Count\`, \`Get\` und \`Check\` können trotz \`POST\` read-only sein.
|
||||
- \`Save\`, \`Add\`, \`Delete\`, \`Remove\`, \`Import\`, \`Publish\` und \`Reset\` sind Mutation.
|
||||
- Mutation wird vor Rate-Budget, Relay-Auflösung und HTTP blockiert.
|
||||
- Der Scoped-Contract enthält nur rekursiv benötigte Schemas und keine tenant-spezifische Server-URL.
|
||||
|
||||
## Operationen
|
||||
|
||||
| ID | Capability | Modus | Methode | Pfad | KWP-Zusammenfassung |
|
||||
|---|---|---|---|---|---|
|
||||
${operationRows}
|
||||
`;
|
||||
}
|
||||
|
||||
function renderTypeScriptCatalog(operations, duplicatePaths, inventory) {
|
||||
const entries = operations
|
||||
.map((operation) => {
|
||||
const value = {
|
||||
id: buildOperationId(operation, duplicatePaths),
|
||||
capability: operation.capability,
|
||||
mode: operation.mode,
|
||||
method: operation.method.toUpperCase(),
|
||||
path: operation.path,
|
||||
};
|
||||
return ` ${JSON.stringify(value)},`;
|
||||
})
|
||||
.join("\n");
|
||||
return `// Generated by scripts/generate-kwp-scoped-contract.mjs. Do not edit manually.
|
||||
export const KWP_SCOPED_OPERATION_INVENTORY = Object.freeze({
|
||||
sourceOperationCount: ${inventory.sourceOperationCount},
|
||||
scopedOperationCount: ${inventory.scopedOperationCount},
|
||||
readOperationCount: ${inventory.readOperationCount},
|
||||
mutationOperationCount: ${inventory.mutationOperationCount},
|
||||
excludedOperationCount: ${inventory.excludedOperationCount},
|
||||
} as const);
|
||||
|
||||
export const KWP_SCOPED_OPERATIONS = Object.freeze([
|
||||
${entries}
|
||||
] as const);
|
||||
|
||||
export type KwpScopedOperation = (typeof KWP_SCOPED_OPERATIONS)[number];
|
||||
export type KwpScopedOperationId = KwpScopedOperation["id"];
|
||||
export type KwpReadOperationId = Extract<KwpScopedOperation, { readonly mode: "read" }>["id"];
|
||||
export type KwpMutationOperationId = Extract<KwpScopedOperation, { readonly mode: "mutation" }>["id"];
|
||||
export type KwpCapability = KwpScopedOperation["capability"];
|
||||
`;
|
||||
}
|
||||
|
||||
function escapeTableText(value) {
|
||||
return value.replaceAll("|", "\\|").replaceAll(/\s+/gu, " ").trim();
|
||||
}
|
||||
Reference in new issue
Block a user