@ybotok/loam 0.0.0 → 0.1.0-beta.2

package/dist/core/arch.js

@@ -0,0 +1,130 @@
+/**
+ * The architecture spec axis — the grammar and resolution of `Covers:`.
+ *
+ * A business spec will never mention the transactional outbox; that is
+ * architecture, and it lives in `arch.spec.md` — same requirement/scenario
+ * grammar as spec.md, same delta algebra, same merge. What is new is the
+ * `Covers:` line: where a business requirement declares the OPERATIONS it
+ * governs, an architecture requirement declares the MODEL OBJECTS its
+ * scenarios exercise, so coverage can be derived mechanically instead of
+ * trusted to an author who was never going to write the outbox down.
+ *
+ * Three entry forms, resolved against the documents loam already reads:
+ *
+ *   paymentService.db               a C4 element id — resolved against the
+ *                                   in-scope elements the way every check joins
+ *                                   them: the id itself, or the service the
+ *                                   element stands for (binding, then title);
+ *   paymentService -> kafka         an edge — each side resolved the same way,
+ *                                   against the declared relationships;
+ *   alert:<id> / sli:<id>           a health signal — ids `health.yaml`
+ *                                   declares (core/health.ts).
+ *
+ * Resolution never reads code. An entry that resolves to nothing is the typo
+ * guard (`covers.unknown`, warn); the emitters live with the other validate
+ * checks, this module owns only the grammar and the matching.
+ */
+import { elementService, serviceResolver } from "./likec4.js";
+/** Parse one comma-separated `Covers:` entry into its form. Never fails: an
+ * unclassifiable string is an element entry that will not resolve, and the
+ * covers.unknown message is a better diagnosis than a parse refusal. */
+export function parseCoversEntry(raw) {
+    const alert = /^alert:\s*(.+)$/.exec(raw);
+    if (alert)
+        return { form: "alert", id: alert[1].trim(), raw };
+    const sli = /^sli:\s*(.+)$/.exec(raw);
+    if (sli)
+        return { form: "sli", id: sli[1].trim(), raw };
+    const edge = /^(.+?)\s*->\s*(.+)$/.exec(raw);
+    if (edge)
+        return { form: "edge", source: edge[1].trim(), target: edge[2].trim(), raw };
+    return { form: "element", id: raw, raw };
+}
+/** Does an element entry name this element? Its id, or the service it stands for. */
+function namesElement(name, e) {
+    return e.id === name || elementService(e) === name;
+}
+/**
+ * One `id -> service` resolver per document, not one per lookup.
+ *
+ * `serviceOf` builds a fresh id map on every call, and this axis calls it twice
+ * for every relationship in scope — inside loops that already run over every
+ * relationship a service can see. `serviceResolver`'s own doc says it is "built
+ * once per document and shared"; this is where the Covers axis keeps that
+ * promise, since `coversEdge` is exported and its callers hold only the element
+ * array.
+ *
+ * A module-level cache is normally the wrong shape here, because a command runs
+ * against whatever directory it was invoked in. This one is safe: the key is the
+ * per-invocation `Elem[]` a parse produced, its value is a pure function of that
+ * key alone, and nothing in it is derived from the working directory — so two
+ * runs can never see each other's answer, and the entry dies with the document.
+ * Nothing mutates an `Elem[]` after parse.
+ */
+const RESOLVERS = new WeakMap();
+function resolverFor(elements) {
+    const cached = RESOLVERS.get(elements);
+    if (cached !== undefined)
+        return cached;
+    const resolver = serviceResolver(elements);
+    RESOLVERS.set(elements, resolver);
+    return resolver;
+}
+/** Does an edge entry's side name this relationship endpoint? */
+function namesEndpoint(name, endpointId, elements) {
+    return endpointId === name || resolverFor(elements)(endpointId) === name;
+}
+/** Does a Covers entry match this element? (Only element entries can.) */
+export function coversElement(entry, e) {
+    return entry.form === "element" && namesElement(entry.id, e);
+}
+/** Does a Covers entry match this relationship? Endpoints resolved within `elements`. */
+export function coversEdge(entry, r, elements) {
+    return (entry.form === "edge" &&
+        namesEndpoint(entry.source, r.source, elements) &&
+        namesEndpoint(entry.target, r.target, elements));
+}
+/** Does the entry resolve to ANYTHING in scope? False is `covers.unknown`. */
+export function entryResolves(entry, scope) {
+    switch (entry.form) {
+        case "alert":
+            return scope.health.alerts.includes(entry.id);
+        case "sli":
+            return scope.health.slis.includes(entry.id);
+        case "edge":
+            return scope.relationships.some((r) => coversEdge(entry, r, scope.elements));
+        case "element":
+            return scope.elements.some((e) => coversElement(entry, e));
+    }
+}
+/** Ids a covers.unknown hint may offer for a mistyped entry — always real ones. */
+export function coversCandidates(entry, scope) {
+    switch (entry.form) {
+        case "alert":
+            return closeIds(entry.id, scope.health.alerts).map((id) => `alert:${id}`);
+        case "sli":
+            return closeIds(entry.id, scope.health.slis).map((id) => `sli:${id}`);
+        case "edge":
+            // Cheap on purpose: no pairwise edge fuzzing — the sides are element
+            // names, so the element hint is the useful one.
+            return [];
+        case "element":
+            return closeIds(entry.id, [...new Set(scope.elements.map((e) => e.id))]);
+    }
+}
+/**
+ * Existing ids near a misspelling — substring containment either way, else a
+ * shared 3-character prefix. Deliberately dumb: no fuzzy library for one hint,
+ * and every id offered is real, so the hint can never point at the typo itself.
+ * (Moved here from validate.ts once `covers.unknown` became its second user.)
+ */
+export function closeIds(typo, ids) {
+    const t = typo.toLowerCase();
+    return ids
+        .filter((id) => {
+        const i = id.toLowerCase();
+        return i.includes(t) || t.includes(i) || (t.length >= 3 && i.startsWith(t.slice(0, 3)));
+    })
+        .slice(0, 5);
+}
+//# sourceMappingURL=arch.js.map

package/dist/core/arch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"arch.js","sourceRoot":"","sources":["../../src/core/arch.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The architecture spec axis — the grammar and resolution of `Covers:`.\n *\n * A business spec will never mention the transactional outbox; that is\n * architecture, and it lives in `arch.spec.md` — same requirement/scenario\n * grammar as spec.md, same delta algebra, same merge. What is new is the\n * `Covers:` line: where a business requirement declares the OPERATIONS it\n * governs, an architecture requirement declares the MODEL OBJECTS its\n * scenarios exercise, so coverage can be derived mechanically instead of\n * trusted to an author who was never going to write the outbox down.\n *\n * Three entry forms, resolved against the documents loam already reads:\n *\n *   paymentService.db               a C4 element id — resolved against the\n *                                   in-scope elements the way every check joins\n *                                   them: the id itself, or the service the\n *                                   element stands for (binding, then title);\n *   paymentService -> kafka         an edge — each side resolved the same way,\n *                                   against the declared relationships;\n *   alert:<id> / sli:<id>           a health signal — ids `health.yaml`\n *                                   declares (core/health.ts).\n *\n * Resolution never reads code. An entry that resolves to nothing is the typo\n * guard (`covers.unknown`, warn); the emitters live with the other validate\n * checks, this module owns only the grammar and the matching.\n */\nimport { elementService, serviceResolver, type Elem, type Rel } from \"./likec4.js\";\nimport type { HealthIds } from \"./health.js\";\n\nexport type CoversEntry =\n  | { form: \"element\"; id: string; raw: string }\n  | { form: \"edge\"; source: string; target: string; raw: string }\n  | { form: \"alert\" | \"sli\"; id: string; raw: string };\n\n/** Parse one comma-separated `Covers:` entry into its form. Never fails: an\n * unclassifiable string is an element entry that will not resolve, and the\n * covers.unknown message is a better diagnosis than a parse refusal. */\nexport function parseCoversEntry(raw: string): CoversEntry {\n  const alert = /^alert:\\s*(.+)$/.exec(raw);\n  if (alert) return { form: \"alert\", id: alert[1]!.trim(), raw };\n  const sli = /^sli:\\s*(.+)$/.exec(raw);\n  if (sli) return { form: \"sli\", id: sli[1]!.trim(), raw };\n  const edge = /^(.+?)\\s*->\\s*(.+)$/.exec(raw);\n  if (edge) return { form: \"edge\", source: edge[1]!.trim(), target: edge[2]!.trim(), raw };\n  return { form: \"element\", id: raw, raw };\n}\n\n/**\n * What `Covers:` entries resolve against: every element and relationship in\n * view (a service's own model plus the landscape; for a feature, the delta\n * plus both), and the health ids of the service whose spec is being read.\n */\nexport interface CoverageScope {\n  elements: Elem[];\n  relationships: Rel[];\n  health: HealthIds;\n}\n\n/** Does an element entry name this element? Its id, or the service it stands for. */\nfunction namesElement(name: string, e: Elem): boolean {\n  return e.id === name || elementService(e) === name;\n}\n\n/**\n * One `id -> service` resolver per document, not one per lookup.\n *\n * `serviceOf` builds a fresh id map on every call, and this axis calls it twice\n * for every relationship in scope — inside loops that already run over every\n * relationship a service can see. `serviceResolver`'s own doc says it is \"built\n * once per document and shared\"; this is where the Covers axis keeps that\n * promise, since `coversEdge` is exported and its callers hold only the element\n * array.\n *\n * A module-level cache is normally the wrong shape here, because a command runs\n * against whatever directory it was invoked in. This one is safe: the key is the\n * per-invocation `Elem[]` a parse produced, its value is a pure function of that\n * key alone, and nothing in it is derived from the working directory — so two\n * runs can never see each other's answer, and the entry dies with the document.\n * Nothing mutates an `Elem[]` after parse.\n */\nconst RESOLVERS = new WeakMap<Elem[], (id: string) => string>();\n\nfunction resolverFor(elements: Elem[]): (id: string) => string {\n  const cached = RESOLVERS.get(elements);\n  if (cached !== undefined) return cached;\n  const resolver = serviceResolver(elements);\n  RESOLVERS.set(elements, resolver);\n  return resolver;\n}\n\n/** Does an edge entry's side name this relationship endpoint? */\nfunction namesEndpoint(name: string, endpointId: string, elements: Elem[]): boolean {\n  return endpointId === name || resolverFor(elements)(endpointId) === name;\n}\n\n/** Does a Covers entry match this element? (Only element entries can.) */\nexport function coversElement(entry: CoversEntry, e: Elem): boolean {\n  return entry.form === \"element\" && namesElement(entry.id, e);\n}\n\n/** Does a Covers entry match this relationship? Endpoints resolved within `elements`. */\nexport function coversEdge(entry: CoversEntry, r: Rel, elements: Elem[]): boolean {\n  return (\n    entry.form === \"edge\" &&\n    namesEndpoint(entry.source, r.source, elements) &&\n    namesEndpoint(entry.target, r.target, elements)\n  );\n}\n\n/** Does the entry resolve to ANYTHING in scope? False is `covers.unknown`. */\nexport function entryResolves(entry: CoversEntry, scope: CoverageScope): boolean {\n  switch (entry.form) {\n    case \"alert\":\n      return scope.health.alerts.includes(entry.id);\n    case \"sli\":\n      return scope.health.slis.includes(entry.id);\n    case \"edge\":\n      return scope.relationships.some((r) => coversEdge(entry, r, scope.elements));\n    case \"element\":\n      return scope.elements.some((e) => coversElement(entry, e));\n  }\n}\n\n/** Ids a covers.unknown hint may offer for a mistyped entry — always real ones. */\nexport function coversCandidates(entry: CoversEntry, scope: CoverageScope): string[] {\n  switch (entry.form) {\n    case \"alert\":\n      return closeIds(entry.id, scope.health.alerts).map((id) => `alert:${id}`);\n    case \"sli\":\n      return closeIds(entry.id, scope.health.slis).map((id) => `sli:${id}`);\n    case \"edge\":\n      // Cheap on purpose: no pairwise edge fuzzing — the sides are element\n      // names, so the element hint is the useful one.\n      return [];\n    case \"element\":\n      return closeIds(entry.id, [...new Set(scope.elements.map((e) => e.id))]);\n  }\n}\n\n/**\n * Existing ids near a misspelling — substring containment either way, else a\n * shared 3-character prefix. Deliberately dumb: no fuzzy library for one hint,\n * and every id offered is real, so the hint can never point at the typo itself.\n * (Moved here from validate.ts once `covers.unknown` became its second user.)\n */\nexport function closeIds(typo: string, ids: string[]): string[] {\n  const t = typo.toLowerCase();\n  return ids\n    .filter((id) => {\n      const i = id.toLowerCase();\n      return i.includes(t) || t.includes(i) || (t.length >= 3 && i.startsWith(t.slice(0, 3)));\n    })\n    .slice(0, 5);\n}\n"]}