@sdd-method/author-cli 0.0.0-stage → 0.1.0

package/dist/lib/sdd-index/repo-config.js

@@ -0,0 +1,245 @@
+/**
+ * Parse orchestration/repo-config/**\/*.yaml into ServiceNode records.
+ *
+ * Accepts both the pre-ADR-0110 shape (contracts as lists of path
+ * strings) and the extended shape (`{path, package?, version?, stability?}`).
+ * Unknown top-level fields are preserved in `ServiceNode.extra` so that
+ * adopter-specific schema additions don't get lost.
+ */
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { walkFiles } from "../sdd-reader.js";
+export const REPO_CONFIG_DIR = "orchestration/repo-config";
+const CONTRACT_KINDS = [
+    "openapi",
+    "proto",
+    "avro",
+    "spicedb",
+];
+export function readAllRepoConfigs(reader) {
+    const services = [];
+    const warnings = [];
+    const files = walkFiles(reader, REPO_CONFIG_DIR, (p) => p.endsWith(".yaml") || p.endsWith(".yml"));
+    for (const relPath of files) {
+        const parsed = parseRepoConfigFile(reader, relPath, warnings);
+        if (parsed)
+            services.push(...expandDeclaredServices(parsed, relPath, warnings));
+    }
+    return { services, warnings };
+}
+/**
+ * M-ADR 0197 §4.6 — expand one parsed repo-config node into N declared
+ * service nodes when the file's `services:` block (preserved unread in
+ * `base.extra.services` by `parseRepoConfigFile`) is present and valid.
+ *
+ * Reuses §4.6's exact primary-selection rule rather than inventing a
+ * second one for this index: the declared entry matching the
+ * repository's own id is primary; failing that, exactly one entry
+ * marked `primary: true`; failing that, attribution is refused with a
+ * warning rather than guessed. Only the primary entry inherits the
+ * file's top-level `dependencies` / `contracts` / `aggregates` — this
+ * model has no fact type below "service", so there is no separate
+ * repo-level node to keep alongside the declared ones. A non-primary
+ * declared entry's own dependencies/contracts stay empty until an
+ * authoring surface for them exists (tracked as a residual gap, not
+ * fixed here — a per-entry-attributed events:/contracts: authoring
+ * mechanism is §4.6's still-unimplemented other half).
+ *
+ * Absent or invalid-shaped `services:`: returns `[base]` unchanged —
+ * byte-exact with today's one-node-per-file behaviour.
+ */
+function expandDeclaredServices(base, relPath, warnings) {
+    const raw = base.extra?.["services"];
+    if (raw === undefined)
+        return [base];
+    if (!Array.isArray(raw)) {
+        warnings.push(`repo-config: ${relPath}: services: must be a list — block dropped, default single-service node kept`);
+        return [base];
+    }
+    const seen = new Set();
+    const entries = [];
+    for (let i = 0; i < raw.length; i++) {
+        const entry = raw[i];
+        if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+            warnings.push(`repo-config: ${relPath}: services[${i}] is not an object — entry dropped`);
+            continue;
+        }
+        const o = entry;
+        const id = typeof o["id"] === "string" ? o["id"].trim() : "";
+        if (id === "") {
+            warnings.push(`repo-config: ${relPath}: services[${i}] missing required "id" — entry dropped`);
+            continue;
+        }
+        if (seen.has(id)) {
+            warnings.push(`repo-config: ${relPath}: services: declares "${id}" more than once — first occurrence kept`);
+            continue;
+        }
+        seen.add(id);
+        entries.push({
+            id,
+            ...(typeof o["domain"] === "string" ? { domain: o["domain"] } : {}),
+            ...(typeof o["service_type"] === "string" ? { serviceType: o["service_type"] } : {}),
+            ...(typeof o["description"] === "string" ? { description: o["description"] } : {}),
+            primary: o["primary"] === true,
+        });
+    }
+    // Present-but-empty (or all-entries-invalid) is authoritative and distinct
+    // from absent, per M-ADR 0197 §4.1 — zero declared services, not the default.
+    if (entries.length === 0)
+        return [];
+    const ownIdEntry = entries.find((e) => e.id === base.id);
+    let primaryId = null;
+    if (ownIdEntry !== undefined) {
+        primaryId = ownIdEntry.id;
+    }
+    else {
+        const explicitPrimaries = entries.filter((e) => e.primary);
+        if (explicitPrimaries.length === 1) {
+            primaryId = explicitPrimaries[0].id;
+        }
+        else if (explicitPrimaries.length > 1) {
+            warnings.push(`repo-config: ${relPath}: services: more than one entry marked primary: true — attribution refused, declare exactly one`);
+        }
+        else {
+            warnings.push(`repo-config: ${relPath}: services: no entry matches the repository's own id ("${base.id}") and none marked primary: true — dependencies/contracts/aggregates cannot be attributed to any declared service`);
+        }
+    }
+    return entries.map((e) => ({
+        id: e.id,
+        domain: e.domain ?? base.domain,
+        ...(e.serviceType ?? base.serviceType ? { serviceType: e.serviceType ?? base.serviceType } : {}),
+        ...(e.description ?? base.description ? { description: e.description ?? base.description } : {}),
+        aggregates: e.id === primaryId ? base.aggregates : [],
+        internalDependencies: e.id === primaryId ? base.internalDependencies : [],
+        contracts: e.id === primaryId ? base.contracts : [],
+        sourcePath: base.sourcePath,
+        // M-ADR 0197 §4.7's fourth failure mode (vacuous): a non-primary
+        // declared entry has no per-entry authoring surface yet, so its empty
+        // fields above are not evidence it has none — flagged here so a
+        // consumer (find_dependencies) can say so rather than presenting an
+        // honest gap as a complete answer.
+        ...(e.id !== primaryId ? { extra: { declaredNonPrimary: true } } : {}),
+    }));
+}
+/**
+ * Parse a single repo-config YAML file. `warnings` is appended to as a
+ * side channel — callers interested in parse quality should pass in a
+ * fresh array.
+ */
+export function parseRepoConfigFile(reader, relPath, warnings) {
+    const raw = reader.readFile(relPath);
+    if (raw === null)
+        return null;
+    let doc;
+    try {
+        doc = parseYaml(raw);
+    }
+    catch (err) {
+        warnings.push(`repo-config: ${relPath} failed to parse as YAML (${err.message})`);
+        return null;
+    }
+    if (!doc || typeof doc !== "object" || Array.isArray(doc)) {
+        warnings.push(`repo-config: ${relPath} is not a YAML mapping`);
+        return null;
+    }
+    const record = doc;
+    // Derive identity from file path: orchestration/repo-config/{domain}/{service}.yaml
+    const pathParts = relPath.split("/");
+    const fileName = pathParts[pathParts.length - 1] ?? "";
+    const derivedDomain = pathParts[pathParts.length - 2];
+    const derivedId = fileName.replace(/\.ya?ml$/, "");
+    const id = stringField(record, "id") ?? stringField(record, "repo") ?? derivedId;
+    const domain = stringField(record, "domain") ?? derivedDomain ?? "";
+    if (!domain) {
+        warnings.push(`repo-config: ${relPath} missing domain (no 'domain' field and no parent directory)`);
+    }
+    const serviceType = stringField(record, "service_type");
+    const description = stringField(record, "description");
+    const aggregates = stringArray(record["aggregates"]);
+    const deps = record["dependencies"];
+    const internalDependencies = deps && typeof deps === "object" && !Array.isArray(deps)
+        ? stringArray(deps["internal"])
+        : [];
+    const contractsRecord = record["contracts"] &&
+        typeof record["contracts"] === "object" &&
+        !Array.isArray(record["contracts"])
+        ? record["contracts"]
+        : {};
+    const contracts = [];
+    for (const kind of CONTRACT_KINDS) {
+        const entries = contractsRecord[kind];
+        if (!Array.isArray(entries))
+            continue;
+        for (const entry of entries) {
+            const ref = parseContractEntry(entry, kind, relPath, warnings);
+            if (ref)
+                contracts.push(ref);
+        }
+    }
+    const reservedKeys = new Set([
+        "id",
+        "repo",
+        "domain",
+        "service_type",
+        "description",
+        "aggregates",
+        "dependencies",
+        "contracts",
+    ]);
+    const extra = {};
+    for (const [k, v] of Object.entries(record)) {
+        if (!reservedKeys.has(k))
+            extra[k] = v;
+    }
+    return {
+        id,
+        domain,
+        ...(serviceType !== undefined ? { serviceType } : {}),
+        ...(description !== undefined ? { description } : {}),
+        aggregates,
+        internalDependencies,
+        contracts,
+        sourcePath: join(reader.sddRoot, relPath),
+        ...(Object.keys(extra).length > 0 ? { extra } : {}),
+    };
+}
+function parseContractEntry(entry, kind, sourceRel, warnings) {
+    if (typeof entry === "string") {
+        return { path: entry, kind };
+    }
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+        warnings.push(`repo-config: ${sourceRel} contains a ${kind} contract entry that is neither string nor mapping`);
+        return null;
+    }
+    const obj = entry;
+    const path = stringField(obj, "path");
+    if (!path) {
+        warnings.push(`repo-config: ${sourceRel} has a ${kind} contract entry with no 'path'`);
+        return null;
+    }
+    const pkg = stringField(obj, "package");
+    const version = stringField(obj, "version");
+    const stability = parseStability(stringField(obj, "stability"));
+    return {
+        path,
+        kind,
+        ...(pkg !== undefined ? { package: pkg } : {}),
+        ...(version !== undefined ? { version } : {}),
+        ...(stability !== undefined ? { stability } : {}),
+    };
+}
+function parseStability(v) {
+    if (v === "provisional" || v === "locked")
+        return v;
+    return undefined;
+}
+function stringField(record, key) {
+    const v = record[key];
+    return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+function stringArray(v) {
+    if (!Array.isArray(v))
+        return [];
+    return v.filter((x) => typeof x === "string");
+}
+//# sourceMappingURL=repo-config.js.map

package/dist/lib/sdd-reader.js

@@ -0,0 +1,91 @@
+/**
+ * SDD content access abstraction: callers read an SDD through an `SddReader`
+ * rooted at the repo, so the reading code does not care where the bytes live.
+ *
+ * Live reads: wrap node:fs.
+ *
+ * Relative paths are rooted at the SDD repo root; absolute paths are
+ * rejected so that callers cannot accidentally escape the SDD.
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+export function liveReader(sddRoot, pin = "HEAD") {
+    const root = sddRoot;
+    const check = (relPath) => {
+        if (isAbsolute(relPath)) {
+            throw new Error(`SddReader paths must be relative to the SDD root; got ${relPath}`);
+        }
+        return join(root, relPath);
+    };
+    return {
+        sddRoot: root,
+        pin,
+        readFile(relPath) {
+            const full = check(relPath);
+            try {
+                return readFileSync(full, "utf8");
+            }
+            catch {
+                return null;
+            }
+        },
+        listDir(relPath) {
+            const full = check(relPath);
+            try {
+                return readdirSync(full);
+            }
+            catch {
+                return [];
+            }
+        },
+        isFile(relPath) {
+            const full = check(relPath);
+            try {
+                return statSync(full).isFile();
+            }
+            catch {
+                return false;
+            }
+        },
+        isDir(relPath) {
+            const full = check(relPath);
+            try {
+                return statSync(full).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}
+/**
+ * Recursive directory walk. Returns relative paths (from SDD root) of
+ * every regular file under `relRoot` that matches the optional filter.
+ * Depth-first, lexicographically sorted at each level for deterministic
+ * index contents.
+ */
+export function walkFiles(reader, relRoot, filter) {
+    const out = [];
+    if (!reader.isDir(relRoot))
+        return out;
+    const stack = [relRoot];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        if (dir === undefined)
+            break;
+        const entries = reader.listDir(dir).sort();
+        for (const entry of entries) {
+            const child = dir === "" ? entry : `${dir}/${entry}`;
+            if (reader.isDir(child)) {
+                stack.push(child);
+            }
+            else if (reader.isFile(child)) {
+                if (!filter || filter(child))
+                    out.push(child);
+            }
+        }
+    }
+    out.sort();
+    return out;
+}
+//# sourceMappingURL=sdd-reader.js.map