@ybotok/loam 0.1.0-beta.3 → 0.2.0-alpha.13

package/dist/core/c4/resolve/systems.js

@@ -0,0 +1,154 @@
+/**
+ * Which drawn elements are SERVICES — asked of a feature's delta, the way the
+ * fleet census asks it of the map.
+ *
+ * The census (`commands/validate/fleet/census.ts`, `drawnSystems`) is the one
+ * answer `validate --all` gives: an element is graded as a service when no
+ * ancestor already stands for one, unless it is a person, somebody else's
+ * system (`#external`), infrastructure the fleet runs, or a GROUPING — an
+ * element that contains a service rather than being one. The feature-scope
+ * graders asked a narrower question of their own. `service.no-requirement-delta`
+ * asked only "is it a `softwareSystem`", so a delta's `#external` producer was
+ * called a new service that owes a requirement delta; the checklist's
+ * `service.exists` asked "is its id dotted", so the same producer became a unit
+ * of work in `loam tasks`, a top-level grouping became a service called after
+ * its title, and the new service FEAT-101 draws inside the map's own group
+ * became a container nobody had to build (the real-fleet review, 2026-10-21).
+ * After the archive, the fleet called every one of those differently.
+ *
+ * It lives in core because those graders do (`core/coherence/`,
+ * `core/verify/`), and core may not import the census. `standsForService`
+ * below is the census's own predicate rung for rung, and the census still
+ * spells its copy: the two must keep answering alike until it imports this
+ * one.
+ *
+ * THREE DELIBERATE NARROWINGS against the census, all because a delta is not a
+ * whole map. An element is looked at only through ancestors the delta DECLARES
+ * and that are themselves groupings — the map's domain or boundary drawn around
+ * the services it re-declares. A level the delta does not declare may be a
+ * living service's own element, and one that stands for no service yet groups
+ * none — a new system's box, an `#external` vendor — is what its children
+ * belong to: a container of a service with no directory yet is that service's,
+ * and an endpoint inside a vendor is the vendor's (`core/gate/partners.ts`
+ * reads it so). And a grouping must stand for no service itself: an element
+ * bound to a service IS one, whatever it contains — the census's answer too
+ * wherever it matters, since a bound or directory-titled element never reaches
+ * its undocumented pass.
+ *
+ * WHAT THE DELTA'S TAGS CANNOT SAY. A delta re-declares the living elements it
+ * attaches to as stubs, usually untagged and always without their living tags,
+ * and the merge keeps the living element's tags — so "is this #external" is a
+ * question about the map the merge leaves, not about the stub. For an element
+ * no directory answers for, `readDeltaSystem` finds the living element it
+ * stands for and asks it the same question.
+ */
+import { existsSync } from "node:fs";
+import {} from "../likec4.js";
+import { properAncestorIds } from "../../kernel/ids/fqn/ancestors.js";
+import { ACTOR_KINDS, EXTERNAL_TAG, INFRA_KINDS } from "../../vocabulary/maturity.js";
+import { drawnServiceElements, elementService } from "./service.js";
+/**
+ * Does this element stand for a `services/<id>/` directory — an explicit
+ * `metadata { service }` binding, or a title naming one `known` holds?
+ */
+function standsForService(e, known) {
+    return e.service !== undefined || known.has(e.title);
+}
+/**
+ * A GROUPING: an element that stands for no service and contains one that
+ * does — a domain, a boundary, an enterprise. There is nothing to bind on it,
+ * no requirement for it to carry and no repository that builds it; the
+ * services under it answer for themselves.
+ */
+export function groupsServices(e, elements, known) {
+    if (standsForService(e, known))
+        return false;
+    const prefix = `${e.id}.`;
+    return elements.some((c) => c.id.startsWith(prefix) && standsForService(c, known));
+}
+/**
+ * Is this element a service-level SYSTEM of ours in the document `elements`
+ * comes from: not a person, not `#external`, not unbound infrastructure, not a
+ * grouping, and drawn only inside groupings that document declares.
+ */
+function isServiceSystem(e, elements, known) {
+    const kind = e.kind.toLowerCase();
+    if (ACTOR_KINDS.has(kind) || e.tags.includes(EXTERNAL_TAG))
+        return false;
+    if (INFRA_KINDS.has(kind) && !standsForService(e, known))
+        return false;
+    const byId = new Map(elements.map((el) => [el.id, el]));
+    for (const id of properAncestorIds(e.id)) {
+        const parent = byId.get(id);
+        if (parent === undefined || !groupsServices(parent, elements, known))
+            return false;
+    }
+    return !groupsServices(e, elements, known);
+}
+/**
+ * What a tagged delta element will be on the map the merge leaves:
+ *
+ * - `none` — not a service: the delta draws it as a person, somebody else's
+ *   system, infrastructure, a grouping or something inside another element —
+ *   or it is the stub of a living element the map draws as one of those;
+ * - `living` — the stub of a service that already has a `services/<id>/`:
+ *   this feature changes it, it does not introduce it;
+ * - `drawn` — a service with no directory that the living map ALREADY draws,
+ *   so this feature re-declares it rather than introducing it either;
+ * - `service` — a service this feature introduces: its directory is the
+ *   feature's own `specs/<id>/`, or nothing has drawn it before.
+ *
+ * The living map is read only for an element no directory answers for — the
+ * one case where the stub's missing tags can be the whole answer — so the
+ * common delta, whose new services all have `specs/`, never parses it. A map
+ * that is absent or does not parse leaves the delta to answer alone, which is
+ * how every element was read before the map was asked.
+ */
+export async function readDeltaSystem(e, scope) {
+    const { elements, known } = scope;
+    if (!isServiceSystem(e, elements, known))
+        return "none";
+    const service = elementService(e);
+    if (scope.living.has(service))
+        return "living";
+    if (known.has(service))
+        return "service";
+    const map = await scope.livingMap();
+    const counterpart = map === null ? undefined : livingCounterpart(e, map, known);
+    if (map === null || counterpart === undefined)
+        return "service";
+    return isServiceSystem(counterpart, map.elements, known) ? "drawn" : "none";
+}
+/**
+ * The living map as `readDeltaSystem` reads it — the caller's
+ * `architecture/landscape.likec4` (`landscapePath`; the path arrives as an
+ * argument because `core/repo/` already imports this package), parsed at most
+ * once per reader and only when first asked; null when there is none or it
+ * does not parse. One reader for every grader that asks, so two of them can
+ * never see different maps for one element.
+ */
+export function livingMapOf(path, load) {
+    let read;
+    return () => (read ??= (async () => {
+        if (!existsSync(path))
+            return null;
+        const doc = await load(path);
+        return doc.errors.length === 0 ? doc : null;
+    })());
+}
+/**
+ * The element of the living map a delta element stands for: the same id, else
+ * the box the map DRAWS for the same service (`drawnServiceElements` — never a
+ * container of some other service that happens to share a title). Undefined
+ * when the map draws nothing of the kind, which for an element no directory
+ * answers for is what makes it new.
+ */
+function livingCounterpart(e, living, known) {
+    const byId = new Map(living.elements.map((el) => [el.id, el]));
+    const same = byId.get(e.id);
+    if (same !== undefined)
+        return same;
+    const drawn = drawnServiceElements(living.elements, known).get(elementService(e));
+    return drawn === undefined ? undefined : byId.get(drawn);
+}
+//# sourceMappingURL=systems.js.map

package/dist/core/c4/resolve/systems.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"systems.js","sourceRoot":"","sources":["../../../../src/core/c4/resolve/systems.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Which drawn elements are SERVICES — asked of a feature's delta, the way the\n * fleet census asks it of the map.\n *\n * The census (`commands/validate/fleet/census.ts`, `drawnSystems`) is the one\n * answer `validate --all` gives: an element is graded as a service when no\n * ancestor already stands for one, unless it is a person, somebody else's\n * system (`#external`), infrastructure the fleet runs, or a GROUPING — an\n * element that contains a service rather than being one. The feature-scope\n * graders asked a narrower question of their own. `service.no-requirement-delta`\n * asked only \"is it a `softwareSystem`\", so a delta's `#external` producer was\n * called a new service that owes a requirement delta; the checklist's\n * `service.exists` asked \"is its id dotted\", so the same producer became a unit\n * of work in `loam tasks`, a top-level grouping became a service called after\n * its title, and the new service FEAT-101 draws inside the map's own group\n * became a container nobody had to build (the real-fleet review, 2026-10-21).\n * After the archive, the fleet called every one of those differently.\n *\n * It lives in core because those graders do (`core/coherence/`,\n * `core/verify/`), and core may not import the census. `standsForService`\n * below is the census's own predicate rung for rung, and the census still\n * spells its copy: the two must keep answering alike until it imports this\n * one.\n *\n * THREE DELIBERATE NARROWINGS against the census, all because a delta is not a\n * whole map. An element is looked at only through ancestors the delta DECLARES\n * and that are themselves groupings — the map's domain or boundary drawn around\n * the services it re-declares. A level the delta does not declare may be a\n * living service's own element, and one that stands for no service yet groups\n * none — a new system's box, an `#external` vendor — is what its children\n * belong to: a container of a service with no directory yet is that service's,\n * and an endpoint inside a vendor is the vendor's (`core/gate/partners.ts`\n * reads it so). And a grouping must stand for no service itself: an element\n * bound to a service IS one, whatever it contains — the census's answer too\n * wherever it matters, since a bound or directory-titled element never reaches\n * its undocumented pass.\n *\n * WHAT THE DELTA'S TAGS CANNOT SAY. A delta re-declares the living elements it\n * attaches to as stubs, usually untagged and always without their living tags,\n * and the merge keeps the living element's tags — so \"is this #external\" is a\n * question about the map the merge leaves, not about the stub. For an element\n * no directory answers for, `readDeltaSystem` finds the living element it\n * stands for and asks it the same question.\n */\nimport { existsSync } from \"node:fs\";\nimport { type Elem, type LoadedDoc } from \"../likec4.js\";\nimport { properAncestorIds } from \"../../kernel/ids/fqn/ancestors.js\";\nimport { ACTOR_KINDS, EXTERNAL_TAG, INFRA_KINDS } from \"../../vocabulary/maturity.js\";\nimport { drawnServiceElements, elementService } from \"./service.js\";\n\n/**\n * Does this element stand for a `services/<id>/` directory — an explicit\n * `metadata { service }` binding, or a title naming one `known` holds?\n */\nfunction standsForService(e: Elem, known: ReadonlySet<string>): boolean {\n  return e.service !== undefined || known.has(e.title);\n}\n\n/**\n * A GROUPING: an element that stands for no service and contains one that\n * does — a domain, a boundary, an enterprise. There is nothing to bind on it,\n * no requirement for it to carry and no repository that builds it; the\n * services under it answer for themselves.\n */\nexport function groupsServices(e: Elem, elements: readonly Elem[], known: ReadonlySet<string>): boolean {\n  if (standsForService(e, known)) return false;\n  const prefix = `${e.id}.`;\n  return elements.some((c) => c.id.startsWith(prefix) && standsForService(c, known));\n}\n\n/**\n * Is this element a service-level SYSTEM of ours in the document `elements`\n * comes from: not a person, not `#external`, not unbound infrastructure, not a\n * grouping, and drawn only inside groupings that document declares.\n */\nfunction isServiceSystem(e: Elem, elements: readonly Elem[], known: ReadonlySet<string>): boolean {\n  const kind = e.kind.toLowerCase();\n  if (ACTOR_KINDS.has(kind) || e.tags.includes(EXTERNAL_TAG)) return false;\n  if (INFRA_KINDS.has(kind) && !standsForService(e, known)) return false;\n  const byId = new Map(elements.map((el) => [el.id, el]));\n  for (const id of properAncestorIds(e.id)) {\n    const parent = byId.get(id);\n    if (parent === undefined || !groupsServices(parent, elements, known)) return false;\n  }\n  return !groupsServices(e, elements, known);\n}\n\n/** What `readDeltaSystem` reads a tagged delta element against. */\nexport interface DeltaSystemScope {\n  /** Every element the delta declares — where its ancestors and children are looked up. */\n  elements: readonly Elem[];\n  /** The directories the merge leaves: the enumerated fleet plus the feature's own `specs/`. */\n  known: ReadonlySet<string>;\n  /** The enumerated fleet alone — the services that already have a `services/<id>/`. */\n  living: ReadonlySet<string>;\n  /** The living map (`livingMapOf`), read only when no directory answers for an element. */\n  livingMap: () => Promise<LoadedDoc | null>;\n}\n\n/**\n * What a tagged delta element will be on the map the merge leaves:\n *\n * - `none` — not a service: the delta draws it as a person, somebody else's\n *   system, infrastructure, a grouping or something inside another element —\n *   or it is the stub of a living element the map draws as one of those;\n * - `living` — the stub of a service that already has a `services/<id>/`:\n *   this feature changes it, it does not introduce it;\n * - `drawn` — a service with no directory that the living map ALREADY draws,\n *   so this feature re-declares it rather than introducing it either;\n * - `service` — a service this feature introduces: its directory is the\n *   feature's own `specs/<id>/`, or nothing has drawn it before.\n *\n * The living map is read only for an element no directory answers for — the\n * one case where the stub's missing tags can be the whole answer — so the\n * common delta, whose new services all have `specs/`, never parses it. A map\n * that is absent or does not parse leaves the delta to answer alone, which is\n * how every element was read before the map was asked.\n */\nexport async function readDeltaSystem(e: Elem, scope: DeltaSystemScope): Promise<\"none\" | \"living\" | \"drawn\" | \"service\"> {\n  const { elements, known } = scope;\n  if (!isServiceSystem(e, elements, known)) return \"none\";\n  const service = elementService(e);\n  if (scope.living.has(service)) return \"living\";\n  if (known.has(service)) return \"service\";\n  const map = await scope.livingMap();\n  const counterpart = map === null ? undefined : livingCounterpart(e, map, known);\n  if (map === null || counterpart === undefined) return \"service\";\n  return isServiceSystem(counterpart, map.elements, known) ? \"drawn\" : \"none\";\n}\n\n/**\n * The living map as `readDeltaSystem` reads it — the caller's\n * `architecture/landscape.likec4` (`landscapePath`; the path arrives as an\n * argument because `core/repo/` already imports this package), parsed at most\n * once per reader and only when first asked; null when there is none or it\n * does not parse. One reader for every grader that asks, so two of them can\n * never see different maps for one element.\n */\nexport function livingMapOf(path: string, load: (path: string) => Promise<LoadedDoc>): () => Promise<LoadedDoc | null> {\n  let read: Promise<LoadedDoc | null> | undefined;\n  return () =>\n    (read ??= (async () => {\n      if (!existsSync(path)) return null;\n      const doc = await load(path);\n      return doc.errors.length === 0 ? doc : null;\n    })());\n}\n\n/**\n * The element of the living map a delta element stands for: the same id, else\n * the box the map DRAWS for the same service (`drawnServiceElements` — never a\n * container of some other service that happens to share a title). Undefined\n * when the map draws nothing of the kind, which for an element no directory\n * answers for is what makes it new.\n */\nfunction livingCounterpart(e: Elem, living: LoadedDoc, known: ReadonlySet<string>): Elem | undefined {\n  const byId = new Map(living.elements.map((el) => [el.id, el]));\n  const same = byId.get(e.id);\n  if (same !== undefined) return same;\n  const drawn = drawnServiceElements(living.elements, known).get(elementService(e));\n  return drawn === undefined ? undefined : byId.get(drawn);\n}\n"]}

package/dist/core/c4/root-project/exclude.js

@@ -0,0 +1,352 @@
+/**
+ * The ONE literal fact loam reads out of the root `likec4.config.json`: which
+ * paths that file excludes from the renderer's root project, and whether a
+ * given directory or document is one of them.
+ *
+ * Until this module existed loam read NOTHING out of that file. It wrote it
+ * once (`core/docs.ts`, `loam init --create`), never re-read it, and the team
+ * owned it from then on — the ownership rule `core/repo/tree/render/projects.ts`
+ * still states for the per-service files. That rule is kept everywhere it still
+ * applies; this is the one exception, and it is earned by what report #05
+ * measured: a model that EXTENDS the fleet map lives in the ROOT project, so
+ * the root's `exclude` decides whether the renderer can see it at all. A repo
+ * whose root config still says `services/**` — every repo scaffolded before
+ * this axis — renders such a model as a box with nothing inside it, and no
+ * check could say why, because nothing here had ever opened the file.
+ *
+ * READ here, and written back by one command only (`loam subsystem sync`,
+ * through `standaloneExclude` in `../service-model/renderer.ts`). Nothing else
+ * about the file is interpreted: `exclude` is a glob list in a tool's own
+ * config, and the entries loam does not recognise as naming a directory are
+ * left exactly where the team put them.
+ *
+ * IT LIVES BELOW `../project/` BECAUSE THE PROJECT LOADER IS A READER. The
+ * architecture document set is the one list every reader shares, and it has to
+ * drop a `.likec4` the root project excludes — a palette under an excluded path
+ * otherwise yields a `global style` reference the fleet project cannot resolve,
+ * `likec4 validate` Invalid on every run and `loam validate --all` at 0 errors
+ * (verification 2026-09-04, W5). `../service-model/` already imports
+ * `../project/`, so this could not stay there without reversing that edge.
+ */
+import { readFile } from "node:fs/promises";
+import { isRecord } from "../../kernel/records.js";
+import { rootProjectPath } from "../../repo/paths.js";
+/** The `services/` prefix every tree path is spelled under, in the config and on disk alike. */
+const SERVICES = "services";
+/**
+ * The root project's `exclude` list, or null when the file cannot be read as a
+ * project config at all.
+ *
+ * The three answers are deliberately distinct, because two of them mean
+ * opposite things to a grader:
+ *
+ *  - `[]` — the file is a JSON object that excludes nothing (or names no
+ *    `exclude` key at all, which is the same thing to the renderer). Every
+ *    extending model is visible; a standalone one is in the root project where
+ *    it cannot parse.
+ *  - a list — the entries as written, in file order.
+ *  - `null` — absent, unreadable, not JSON, or JSON whose `exclude` is not a
+ *    list of strings. loam does not know what the renderer will do, so it says
+ *    nothing rather than guessing: the findings that read this list are silent
+ *    on null, `subsystem sync` leaves such a file alone, and the project loader
+ *    filters nothing. Failing closed here means the team keeps a file loam
+ *    cannot parse; failing open would mean loam asserting the renderer excludes
+ *    something on evidence it does not have.
+ */
+export async function readRootExclude(docsDir) {
+    const parsed = await readRootProject(docsDir);
+    if (parsed === null)
+        return null;
+    const exclude = parsed["exclude"];
+    if (exclude === undefined)
+        return [];
+    if (!Array.isArray(exclude))
+        return null;
+    // A predicate rather than a cast, so the narrowing below is the compiler's
+    // conclusion from a check that actually ran: an `exclude` holding a number is
+    // a file loam does not understand, and understanding it half way is how a
+    // grader ends up asserting a glob nobody wrote.
+    const entries = exclude;
+    return entries.every((entry) => typeof entry === "string") ? [...entries] : null;
+}
+/**
+ * The root project file as a JSON object, or null when it is absent or is not
+ * one — the ONE reader, shared with the one writer that re-parses it before a
+ * rewrite (`commands/subsystem/txn/exclude.ts`).
+ *
+ * A LEADING BYTE-ORDER MARK IS STRIPPED, and that is not tidiness: PowerShell's
+ * `Out-File` writes `ef bb bf` by default on this platform, so a Windows shell
+ * saving the very file loam wrote left `JSON.parse` throwing while the renderer
+ * — whose reader tolerates the mark — went on applying every entry in the list.
+ * loam then graded nothing at all: `validate --all` silent about an exclusion in
+ * full force, `doctor` healthy, `subsystem sync` reporting the list unreadable
+ * and naming a fault (`not a JSON object with a string exclude list`) that was
+ * not the one present (re-verification 2026-09-04, area C item 3). One reader
+ * means the grade and the rewrite can never disagree about whether the file
+ * parses.
+ */
+async function readRootProject(docsDir) {
+    let text;
+    try {
+        text = await readFile(rootProjectPath(docsDir), "utf8");
+    }
+    catch {
+        // Absent reads as "loam cannot say", not as "excludes nothing": a docs repo
+        // with no root project file has no root project either, and the renderer
+        // opened there shows nothing at all — a different problem, with a different
+        // finding (`doctor.likec4-config-missing`).
+        return null;
+    }
+    return parseRootProject(text);
+}
+/** The byte-order mark PowerShell's `Out-File` prepends by default on this platform. */
+const BOM = "";
+/** The same parse, over bytes a caller already read. Exported for the rewrite path only. */
+export function parseRootProject(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text.startsWith(BOM) ? text.slice(BOM.length) : text);
+    }
+    catch {
+        // Not JSON is the team's file to fix, and nothing here may rewrite it.
+        return null;
+    }
+    return isRecord(parsed) ? parsed : null;
+}
+/** A PATH as segments — `/` or `\`, either spelling, no empty parts, no `.`. Never an ENTRY: see `rendererEntry`. */
+function segments(path) {
+    return path.split(/[\\/]/).filter((s) => s.length > 0 && s !== ".");
+}
+function rendererEntry(entry) {
+    if (entry.includes("\\"))
+        return null;
+    let rest = entry;
+    let anchored = false;
+    if (rest.startsWith("./")) {
+        rest = rest.slice(2);
+        anchored = true;
+        // `.//x` — the dot survives as a literal directory name, so the pattern
+        // names a path nothing on disk has.
+        if (rest.startsWith("/"))
+            return null;
+    }
+    else if (rest.startsWith("../")) {
+        return null;
+    }
+    const trailing = rest.endsWith("/");
+    const parts = [];
+    for (const part of rest.split("/")) {
+        if (part.length === 0 || part === ".")
+            continue;
+        if (part === "..") {
+            if (parts.pop() === undefined)
+                return null;
+            continue;
+        }
+        parts.push(part);
+    }
+    // An entry that normalises to nothing at all is the project folder itself,
+    // which `contains: true` makes a match for every document under it.
+    const glob = parts.length === 0 ? "**" : `${parts.join("/")}${trailing ? "/" : ""}`;
+    return { glob, anchored: anchored && parts.length > 0 };
+}
+/** The expression one entry matches with, or null when it matches nothing — `rendererEntry` says which. */
+function matcherFor(parsed, glob) {
+    return new RegExp(`^${globSource(parsed.anchored ? glob : prefixed(glob))}`);
+}
+/**
+ * An entry's segments with the trailing bare wildcards taken off — the question
+ * "which directory is this line ABOUT", asked of the four spellings that name
+ * one: `services/pay` doubled-star, that entry with a trailing `/*` after it,
+ * `services/pay/*` and `services/pay/` all reduce to `services/pay`. A wildcard
+ * that is NOT trailing survives — one segment of its own — because a starred
+ * middle segment picks one directory level and no more.
+ *
+ * It is NOT the covering rule. What an entry HIDES is `entryRegex` below, and
+ * the two answer differently on purpose: `services/pay/**` is about the
+ * directory `services/pay`, while the bare `services/pay` hides
+ * `services/payment-service` as well (measured — see below).
+ *
+ * It takes the NORMALISED glob, never the raw entry: an entry is split on `/`
+ * alone, because a backslash is a literal to the renderer and splitting on it
+ * here was what made `services\order-service\**` read as naming a directory it
+ * hides nothing in.
+ */
+function patternSegments(glob) {
+    const parts = glob.split("/").filter((part) => part.length > 0);
+    while (parts.length > 0 && (parts.at(-1) === "*" || parts.at(-1) === "**"))
+        parts.pop();
+    return parts;
+}
+/**
+ * One `exclude` entry as the expression the RENDERER matches paths with:
+ * anchored at the start of a path segment, and NOT anchored at the end.
+ *
+ * MEASURED, at the 1.59.2 pin, on a scratch fleet of five documents —
+ * `architecture/landscape.likec4`, `architecture/usecases/uc.likec4`,
+ * `services/payment-service/model.likec4`,
+ * `services/payments/payment-service/model.likec4` and
+ * `services/order-service/model.likec4` — counting the "N files" `npx likec4
+ * validate .` reports with one entry in the list:
+ *
+ *   services/zzz                5    services/pay                3
+ *   services/payment-service    4    a star as the middle segment  4
+ *   services/pay/**             5    architect                   3
+ *   architecture/*.likec4       4    *.likec4                    0
+ *   ervices                     5    ces/payment-service         5
+ *   payment-service             3    services/**                 2
+ *   services                    2    services/payment-service/*  hides a nested file too
+ *
+ * Four rules come out of that table, and every one of them contradicts what
+ * this module asserted before (verification 2026-09-04, review C): the match is
+ * a raw PREFIX with no end anchor (`services/pay` takes both payment trees,
+ * `architect` takes all of `architecture/`); it must START on a `/` boundary
+ * (`ervices` and `ces/payment-service` take nothing); `*` stays inside one
+ * segment (`architecture/*.likec4` leaves `architecture/usecases/uc.likec4`);
+ * and a glob form does NOT prefix-match (`services/pay/**` needs the literal
+ * separator, so it takes nothing from `services/payment-service`).
+ *
+ * The shape falls out of what LikeC4 does with the list: an entry that does not
+ * already begin with a doubled star is prefixed with one, joined onto the
+ * project folder and handed to picomatch with `contains: true` — and `contains`
+ * is exactly the missing end anchor. So the optional any-directories group
+ * `globSource` emits for a leading doubled star IS that prefix, and the absent
+ * `$` is that option.
+ *
+ * NULL when the entry hides nothing at all — `rendererEntry` names the two
+ * spellings that do, and every caller has to skip such an entry rather than
+ * treat it as covering: a warning derived from one sent a team after a line the
+ * renderer ignores, and `subsystem sync` then deleted it.
+ */
+function entryRegex(entry) {
+    const parsed = rendererEntry(entry);
+    return parsed === null ? null : matcherFor(parsed, parsed.glob);
+}
+/** An entry as LikeC4 spells it before matching: a doubled star in front, unless it has one. */
+function prefixed(entry) {
+    return entry.startsWith("**") ? entry : `**/${entry}`;
+}
+/**
+ * A glob as a regular-expression SOURCE. `**` crosses `/` and, followed by a
+ * separator, may stand for no directory at all (a doubled star between two literals matches with no directory between them, which
+ * is what makes a doubled-star-then-star entry cover a model directly under `services/`);
+ * `*` and `?` never cross one.
+ */
+function globSource(pattern) {
+    let source = "";
+    let i = 0;
+    while (i < pattern.length) {
+        if (pattern.startsWith("**/", i)) {
+            source += "(?:.*/)?";
+            i += 3;
+            continue;
+        }
+        if (pattern.startsWith("**", i)) {
+            source += ".*";
+            i += 2;
+            continue;
+        }
+        const c = pattern[i];
+        if (c === "*")
+            source += "[^/]*";
+        else if (c === "?")
+            source += "[^/]";
+        else
+            source += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+        i += 1;
+    }
+    return source;
+}
+/**
+ * The entry that hides `relPath` from the root project, or null when nothing in
+ * the list does. `relPath` is a docs-relative FILE path, spelled either way
+ * round the slash.
+ *
+ * Returned VERBATIM because every message that carries it asks its reader to
+ * delete or narrow THAT line, and an entry re-spelled by loam is a line they
+ * would go looking for and not find.
+ */
+export function excludingPath(exclude, relPath) {
+    const path = segments(relPath).join("/");
+    if (path.length === 0)
+        return null;
+    for (const entry of exclude) {
+        if (entryRegex(entry)?.test(path) === true)
+            return entry;
+    }
+    return null;
+}
+/**
+ * The entry that hides a SERVICE TREE — the directory and everything under it —
+ * or null. The tree's spelling is normalised here because the repository writes
+ * it both ways: `serviceTreePath` includes the leading `services/` and the
+ * entries `standaloneExclude` writes are built from the part under it, and
+ * getting that wrong would silently answer "not excluded" for every service.
+ *
+ * A DIRECTORY IS NOT A FILE, and that is why this is not `excludingPath` on the
+ * directory's own path. `services/payment-service/**` hides every document in
+ * that tree while matching no prefix of the directory string itself — the
+ * pattern wants the separator the directory path ends before. So a second arm
+ * asks the other half: does the directory the entry NAMES (`patternSegments`,
+ * the trailing wildcards off) contain this tree? Asking it of the named
+ * directory rather than of the raw prefix is what keeps `services/pay/**` about
+ * `services/pay` and away from `services/payment-service`, which is exactly
+ * where the renderer leaves it.
+ *
+ * What this deliberately does NOT report is an entry that hides only PART of a
+ * tree (`services/x/model`, say). The four findings that read this answer are
+ * about a directory the renderer either loads or does not, and half of one is a
+ * state `subsystem sync` has no entry to write for.
+ */
+export function excludingEntry(exclude, treePath) {
+    const tree = segments(treePath).join("/");
+    if (tree.length === 0)
+        return null;
+    const full = tree === SERVICES || tree.startsWith(`${SERVICES}/`) ? tree : `${SERVICES}/${tree}`;
+    for (const entry of exclude) {
+        if (coversTree(entry, full))
+            return entry;
+    }
+    return null;
+}
+/** Does one entry hide `dir` and everything under it? The two arms `excludingEntry` documents. */
+function coversTree(entry, dir) {
+    const parsed = rendererEntry(entry);
+    // An entry that hides nothing covers nothing — the backslash spelling, which
+    // loam used to read as covering the tree while the renderer loaded every file
+    // in it (measured: 8 of 8), warning `service.model-excluded` about a healthy
+    // service and then deleting the team's line on the next sync.
+    if (parsed === null)
+        return false;
+    if (matcherFor(parsed, parsed.glob).test(dir))
+        return true;
+    const named = patternSegments(parsed.glob);
+    if (named.length === 0)
+        return false;
+    // The named directory, or an ancestor of it, matched on a segment boundary —
+    // never mid-segment, which is the whole difference between this arm and the
+    // prefix one above.
+    return new RegExp(`${matcherFor(parsed, named.join("/")).source}(?:/|$)`).test(dir);
+}
+/**
+ * The DIRECTORY an entry names, `/`-joined, or null when the entry does not
+ * plainly name one — a wildcard segment between two literal ones, or the
+ * leading doubled star of the `node_modules` glob.
+ *
+ * The trailing wildcards are what get stripped: `services/pay` doubled-star and
+ * the three other spellings `patternSegments` lists all name `services/pay`. It
+ * is the AUTHORSHIP question the writer asks — "did loam write this line, and is
+ * it about a directory the enumeration returns?" — never the covering one, which
+ * is `excludingEntry`'s.
+ */
+export function excludedDirectory(entry) {
+    const parsed = rendererEntry(entry);
+    // An entry that hides nothing names nothing either, so a backslash spelling is
+    // never loam's to rewrite: `subsystem sync` leaves it exactly where the team
+    // put it, which is the only honest answer about a line the renderer ignores.
+    if (parsed === null)
+        return null;
+    const parts = patternSegments(parsed.glob);
+    return parts.some((part) => part.includes("*")) ? null : parts.join("/");
+}
+//# sourceMappingURL=exclude.js.map

package/dist/core/c4/root-project/exclude.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exclude.js","sourceRoot":"","sources":["../../../../src/core/c4/root-project/exclude.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The ONE literal fact loam reads out of the root `likec4.config.json`: which\n * paths that file excludes from the renderer's root project, and whether a\n * given directory or document is one of them.\n *\n * Until this module existed loam read NOTHING out of that file. It wrote it\n * once (`core/docs.ts`, `loam init --create`), never re-read it, and the team\n * owned it from then on — the ownership rule `core/repo/tree/render/projects.ts`\n * still states for the per-service files. That rule is kept everywhere it still\n * applies; this is the one exception, and it is earned by what report #05\n * measured: a model that EXTENDS the fleet map lives in the ROOT project, so\n * the root's `exclude` decides whether the renderer can see it at all. A repo\n * whose root config still says `services/**` — every repo scaffolded before\n * this axis — renders such a model as a box with nothing inside it, and no\n * check could say why, because nothing here had ever opened the file.\n *\n * READ here, and written back by one command only (`loam subsystem sync`,\n * through `standaloneExclude` in `../service-model/renderer.ts`). Nothing else\n * about the file is interpreted: `exclude` is a glob list in a tool's own\n * config, and the entries loam does not recognise as naming a directory are\n * left exactly where the team put them.\n *\n * IT LIVES BELOW `../project/` BECAUSE THE PROJECT LOADER IS A READER. The\n * architecture document set is the one list every reader shares, and it has to\n * drop a `.likec4` the root project excludes — a palette under an excluded path\n * otherwise yields a `global style` reference the fleet project cannot resolve,\n * `likec4 validate` Invalid on every run and `loam validate --all` at 0 errors\n * (verification 2026-09-04, W5). `../service-model/` already imports\n * `../project/`, so this could not stay there without reversing that edge.\n */\nimport { readFile } from \"node:fs/promises\";\nimport { isRecord } from \"../../kernel/records.js\";\nimport type { DocsDir } from \"../../kernel/ids/dirs.js\";\nimport { rootProjectPath } from \"../../repo/paths.js\";\n\n/** The `services/` prefix every tree path is spelled under, in the config and on disk alike. */\nconst SERVICES = \"services\";\n\n/**\n * The root project's `exclude` list, or null when the file cannot be read as a\n * project config at all.\n *\n * The three answers are deliberately distinct, because two of them mean\n * opposite things to a grader:\n *\n *  - `[]` — the file is a JSON object that excludes nothing (or names no\n *    `exclude` key at all, which is the same thing to the renderer). Every\n *    extending model is visible; a standalone one is in the root project where\n *    it cannot parse.\n *  - a list — the entries as written, in file order.\n *  - `null` — absent, unreadable, not JSON, or JSON whose `exclude` is not a\n *    list of strings. loam does not know what the renderer will do, so it says\n *    nothing rather than guessing: the findings that read this list are silent\n *    on null, `subsystem sync` leaves such a file alone, and the project loader\n *    filters nothing. Failing closed here means the team keeps a file loam\n *    cannot parse; failing open would mean loam asserting the renderer excludes\n *    something on evidence it does not have.\n */\nexport async function readRootExclude(docsDir: DocsDir): Promise<string[] | null> {\n  const parsed = await readRootProject(docsDir);\n  if (parsed === null) return null;\n  const exclude = parsed[\"exclude\"];\n  if (exclude === undefined) return [];\n  if (!Array.isArray(exclude)) return null;\n  // A predicate rather than a cast, so the narrowing below is the compiler's\n  // conclusion from a check that actually ran: an `exclude` holding a number is\n  // a file loam does not understand, and understanding it half way is how a\n  // grader ends up asserting a glob nobody wrote.\n  const entries: unknown[] = exclude;\n  return entries.every((entry): entry is string => typeof entry === \"string\") ? [...entries] : null;\n}\n\n/**\n * The root project file as a JSON object, or null when it is absent or is not\n * one — the ONE reader, shared with the one writer that re-parses it before a\n * rewrite (`commands/subsystem/txn/exclude.ts`).\n *\n * A LEADING BYTE-ORDER MARK IS STRIPPED, and that is not tidiness: PowerShell's\n * `Out-File` writes `ef bb bf` by default on this platform, so a Windows shell\n * saving the very file loam wrote left `JSON.parse` throwing while the renderer\n * — whose reader tolerates the mark — went on applying every entry in the list.\n * loam then graded nothing at all: `validate --all` silent about an exclusion in\n * full force, `doctor` healthy, `subsystem sync` reporting the list unreadable\n * and naming a fault (`not a JSON object with a string exclude list`) that was\n * not the one present (re-verification 2026-09-04, area C item 3). One reader\n * means the grade and the rewrite can never disagree about whether the file\n * parses.\n */\nasync function readRootProject(docsDir: DocsDir): Promise<Record<string, unknown> | null> {\n  let text: string;\n  try {\n    text = await readFile(rootProjectPath(docsDir), \"utf8\");\n  } catch {\n    // Absent reads as \"loam cannot say\", not as \"excludes nothing\": a docs repo\n    // with no root project file has no root project either, and the renderer\n    // opened there shows nothing at all — a different problem, with a different\n    // finding (`doctor.likec4-config-missing`).\n    return null;\n  }\n  return parseRootProject(text);\n}\n\n/** The byte-order mark PowerShell's `Out-File` prepends by default on this platform. */\nconst BOM = \"\";\n\n/** The same parse, over bytes a caller already read. Exported for the rewrite path only. */\nexport function parseRootProject(text: string): Record<string, unknown> | null {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(text.startsWith(BOM) ? text.slice(BOM.length) : text);\n  } catch {\n    // Not JSON is the team's file to fix, and nothing here may rewrite it.\n    return null;\n  }\n  return isRecord(parsed) ? parsed : null;\n}\n\n/** A PATH as segments — `/` or `\\`, either spelling, no empty parts, no `.`. Never an ENTRY: see `rendererEntry`. */\nfunction segments(path: string): string[] {\n  return path.split(/[\\\\/]/).filter((s) => s.length > 0 && s !== \".\");\n}\n\n/**\n * One `exclude` entry as the RENDERER will match it — the glob with the\n * spellings that mean nothing to it taken out — or null when the entry can hide\n * nothing loam is able to spell.\n *\n * WHY IT EXISTS. Every matcher below used to build its expression from the entry\n * exactly as written while normalising only the PATH, so four spellings of one\n * line disagreed with the renderer in loam's favour: `./architecture/palette.likec4`,\n * `architecture/./palette.likec4` and `architecture//palette.likec4` each hid the\n * palette from `likec4 validate` (8 source files, down from 9) and from nothing\n * in loam — the census loaded it, `subsystem sync` wrote a `global style\n * subsystems` line naming a group the fleet project cannot resolve, and the run\n * reported 0 errors while every render was Invalid. `./architecture/**` did the\n * same to the whole map with `landscape.excluded` silent (re-verification\n * 2026-09-04, area C items 1-2).\n *\n * MEASURED, at the 1.59.2 pin, against the renderer's own matcher — likec4\n * builds `withoutDoubleSlashes(joinRelativeURL(<project folder>, entry))` (a\n * doubled star and a slash joined in front unless the entry already leads with\n * one or is spelled relative) and hands it to picomatch with `contains: true,\n * dot: true`. The rules that fall out, each pinned in\n * `test/root-exclude.test.ts` against a `npx likec4 validate .` file count:\n *\n *  - a leading `./` is resolved, and it ANCHORS the entry at the docs root —\n *    the any-directories prefix is not added, so `./architecture/**` is about that one\n *    directory and `architecture/**` is about one at any depth;\n *  - `/./` and `//` inside the entry collapse (`architecture//palette.likec4`\n *    hides the palette exactly as the plain spelling does);\n *  - a TRAILING `/` does not: `architecture` hides `architecture-old/old.likec4`\n *    as a raw prefix and `architecture/` does not (measured 5 files vs 6), so\n *    the slash is kept rather than stripped;\n *  - `.//` keeps a literal `.` directory in the pattern and matches NOTHING\n *    (measured: 10 files of 10);\n *  - a BACKSLASH is a literal character to picomatch, never a separator, so\n *    `services\\order-service\\**` hides nothing at all (measured: 8 files of 8)\n *    — loam used to read it as covering the tree, warn `service.model-excluded`\n *    about a service the renderer loads perfectly well, and then DELETE the\n *    team's line on the next `subsystem sync`.\n *\n * The two arms that answer null are the entries loam declines to reason about:\n * a backslash-bearing one (it covers nothing, so nothing may be graded on it)\n * and one whose `..` walks above the docs root, where the renderer's pattern\n * stops describing this tree at all.\n */\ninterface RendererEntry {\n  /** The glob, `/`-separated, `.` segments resolved and `//` collapsed, any trailing `/` kept. */\n  glob: string;\n  /** True when a leading `./` anchored the entry at the docs root instead of at any depth. */\n  anchored: boolean;\n}\n\nfunction rendererEntry(entry: string): RendererEntry | null {\n  if (entry.includes(\"\\\\\")) return null;\n  let rest = entry;\n  let anchored = false;\n  if (rest.startsWith(\"./\")) {\n    rest = rest.slice(2);\n    anchored = true;\n    // `.//x` — the dot survives as a literal directory name, so the pattern\n    // names a path nothing on disk has.\n    if (rest.startsWith(\"/\")) return null;\n  } else if (rest.startsWith(\"../\")) {\n    return null;\n  }\n  const trailing = rest.endsWith(\"/\");\n  const parts: string[] = [];\n  for (const part of rest.split(\"/\")) {\n    if (part.length === 0 || part === \".\") continue;\n    if (part === \"..\") {\n      if (parts.pop() === undefined) return null;\n      continue;\n    }\n    parts.push(part);\n  }\n  // An entry that normalises to nothing at all is the project folder itself,\n  // which `contains: true` makes a match for every document under it.\n  const glob = parts.length === 0 ? \"**\" : `${parts.join(\"/\")}${trailing ? \"/\" : \"\"}`;\n  return { glob, anchored: anchored && parts.length > 0 };\n}\n\n/** The expression one entry matches with, or null when it matches nothing — `rendererEntry` says which. */\nfunction matcherFor(parsed: RendererEntry, glob: string): RegExp {\n  return new RegExp(`^${globSource(parsed.anchored ? glob : prefixed(glob))}`);\n}\n\n/**\n * An entry's segments with the trailing bare wildcards taken off — the question\n * \"which directory is this line ABOUT\", asked of the four spellings that name\n * one: `services/pay` doubled-star, that entry with a trailing `/*` after it,\n * `services/pay/*` and `services/pay/` all reduce to `services/pay`. A wildcard\n * that is NOT trailing survives — one segment of its own — because a starred\n * middle segment picks one directory level and no more.\n *\n * It is NOT the covering rule. What an entry HIDES is `entryRegex` below, and\n * the two answer differently on purpose: `services/pay/**` is about the\n * directory `services/pay`, while the bare `services/pay` hides\n * `services/payment-service` as well (measured — see below).\n *\n * It takes the NORMALISED glob, never the raw entry: an entry is split on `/`\n * alone, because a backslash is a literal to the renderer and splitting on it\n * here was what made `services\\order-service\\**` read as naming a directory it\n * hides nothing in.\n */\nfunction patternSegments(glob: string): string[] {\n  const parts = glob.split(\"/\").filter((part) => part.length > 0);\n  while (parts.length > 0 && (parts.at(-1) === \"*\" || parts.at(-1) === \"**\")) parts.pop();\n  return parts;\n}\n\n/**\n * One `exclude` entry as the expression the RENDERER matches paths with:\n * anchored at the start of a path segment, and NOT anchored at the end.\n *\n * MEASURED, at the 1.59.2 pin, on a scratch fleet of five documents —\n * `architecture/landscape.likec4`, `architecture/usecases/uc.likec4`,\n * `services/payment-service/model.likec4`,\n * `services/payments/payment-service/model.likec4` and\n * `services/order-service/model.likec4` — counting the \"N files\" `npx likec4\n * validate .` reports with one entry in the list:\n *\n *   services/zzz                5    services/pay                3\n *   services/payment-service    4    a star as the middle segment  4\n *   services/pay/**             5    architect                   3\n *   architecture/*.likec4       4    *.likec4                    0\n *   ervices                     5    ces/payment-service         5\n *   payment-service             3    services/**                 2\n *   services                    2    services/payment-service/*  hides a nested file too\n *\n * Four rules come out of that table, and every one of them contradicts what\n * this module asserted before (verification 2026-09-04, review C): the match is\n * a raw PREFIX with no end anchor (`services/pay` takes both payment trees,\n * `architect` takes all of `architecture/`); it must START on a `/` boundary\n * (`ervices` and `ces/payment-service` take nothing); `*` stays inside one\n * segment (`architecture/*.likec4` leaves `architecture/usecases/uc.likec4`);\n * and a glob form does NOT prefix-match (`services/pay/**` needs the literal\n * separator, so it takes nothing from `services/payment-service`).\n *\n * The shape falls out of what LikeC4 does with the list: an entry that does not\n * already begin with a doubled star is prefixed with one, joined onto the\n * project folder and handed to picomatch with `contains: true` — and `contains`\n * is exactly the missing end anchor. So the optional any-directories group\n * `globSource` emits for a leading doubled star IS that prefix, and the absent\n * `$` is that option.\n *\n * NULL when the entry hides nothing at all — `rendererEntry` names the two\n * spellings that do, and every caller has to skip such an entry rather than\n * treat it as covering: a warning derived from one sent a team after a line the\n * renderer ignores, and `subsystem sync` then deleted it.\n */\nfunction entryRegex(entry: string): RegExp | null {\n  const parsed = rendererEntry(entry);\n  return parsed === null ? null : matcherFor(parsed, parsed.glob);\n}\n\n/** An entry as LikeC4 spells it before matching: a doubled star in front, unless it has one. */\nfunction prefixed(entry: string): string {\n  return entry.startsWith(\"**\") ? entry : `**/${entry}`;\n}\n\n/**\n * A glob as a regular-expression SOURCE. `**` crosses `/` and, followed by a\n * separator, may stand for no directory at all (a doubled star between two literals matches with no directory between them, which\n * is what makes a doubled-star-then-star entry cover a model directly under `services/`);\n * `*` and `?` never cross one.\n */\nfunction globSource(pattern: string): string {\n  let source = \"\";\n  let i = 0;\n  while (i < pattern.length) {\n    if (pattern.startsWith(\"**/\", i)) {\n      source += \"(?:.*/)?\";\n      i += 3;\n      continue;\n    }\n    if (pattern.startsWith(\"**\", i)) {\n      source += \".*\";\n      i += 2;\n      continue;\n    }\n    const c = pattern[i]!;\n    if (c === \"*\") source += \"[^/]*\";\n    else if (c === \"?\") source += \"[^/]\";\n    else source += c.replace(/[.+^${}()|[\\]\\\\]/g, \"\\\\$&\");\n    i += 1;\n  }\n  return source;\n}\n\n/**\n * The entry that hides `relPath` from the root project, or null when nothing in\n * the list does. `relPath` is a docs-relative FILE path, spelled either way\n * round the slash.\n *\n * Returned VERBATIM because every message that carries it asks its reader to\n * delete or narrow THAT line, and an entry re-spelled by loam is a line they\n * would go looking for and not find.\n */\nexport function excludingPath(exclude: readonly string[], relPath: string): string | null {\n  const path = segments(relPath).join(\"/\");\n  if (path.length === 0) return null;\n  for (const entry of exclude) {\n    if (entryRegex(entry)?.test(path) === true) return entry;\n  }\n  return null;\n}\n\n/**\n * The entry that hides a SERVICE TREE — the directory and everything under it —\n * or null. The tree's spelling is normalised here because the repository writes\n * it both ways: `serviceTreePath` includes the leading `services/` and the\n * entries `standaloneExclude` writes are built from the part under it, and\n * getting that wrong would silently answer \"not excluded\" for every service.\n *\n * A DIRECTORY IS NOT A FILE, and that is why this is not `excludingPath` on the\n * directory's own path. `services/payment-service/**` hides every document in\n * that tree while matching no prefix of the directory string itself — the\n * pattern wants the separator the directory path ends before. So a second arm\n * asks the other half: does the directory the entry NAMES (`patternSegments`,\n * the trailing wildcards off) contain this tree? Asking it of the named\n * directory rather than of the raw prefix is what keeps `services/pay/**` about\n * `services/pay` and away from `services/payment-service`, which is exactly\n * where the renderer leaves it.\n *\n * What this deliberately does NOT report is an entry that hides only PART of a\n * tree (`services/x/model`, say). The four findings that read this answer are\n * about a directory the renderer either loads or does not, and half of one is a\n * state `subsystem sync` has no entry to write for.\n */\nexport function excludingEntry(exclude: readonly string[], treePath: string): string | null {\n  const tree = segments(treePath).join(\"/\");\n  if (tree.length === 0) return null;\n  const full = tree === SERVICES || tree.startsWith(`${SERVICES}/`) ? tree : `${SERVICES}/${tree}`;\n  for (const entry of exclude) {\n    if (coversTree(entry, full)) return entry;\n  }\n  return null;\n}\n\n/** Does one entry hide `dir` and everything under it? The two arms `excludingEntry` documents. */\nfunction coversTree(entry: string, dir: string): boolean {\n  const parsed = rendererEntry(entry);\n  // An entry that hides nothing covers nothing — the backslash spelling, which\n  // loam used to read as covering the tree while the renderer loaded every file\n  // in it (measured: 8 of 8), warning `service.model-excluded` about a healthy\n  // service and then deleting the team's line on the next sync.\n  if (parsed === null) return false;\n  if (matcherFor(parsed, parsed.glob).test(dir)) return true;\n  const named = patternSegments(parsed.glob);\n  if (named.length === 0) return false;\n  // The named directory, or an ancestor of it, matched on a segment boundary —\n  // never mid-segment, which is the whole difference between this arm and the\n  // prefix one above.\n  return new RegExp(`${matcherFor(parsed, named.join(\"/\")).source}(?:/|$)`).test(dir);\n}\n\n/**\n * The DIRECTORY an entry names, `/`-joined, or null when the entry does not\n * plainly name one — a wildcard segment between two literal ones, or the\n * leading doubled star of the `node_modules` glob.\n *\n * The trailing wildcards are what get stripped: `services/pay` doubled-star and\n * the three other spellings `patternSegments` lists all name `services/pay`. It\n * is the AUTHORSHIP question the writer asks — \"did loam write this line, and is\n * it about a directory the enumeration returns?\" — never the covering one, which\n * is `excludingEntry`'s.\n */\nexport function excludedDirectory(entry: string): string | null {\n  const parsed = rendererEntry(entry);\n  // An entry that hides nothing names nothing either, so a backslash spelling is\n  // never loam's to rewrite: `subsystem sync` leaves it exactly where the team\n  // put it, which is the only honest answer about a line the renderer ignores.\n  if (parsed === null) return null;\n  const parts = patternSegments(parsed.glob);\n  return parts.some((part) => part.includes(\"*\")) ? null : parts.join(\"/\");\n}\n"]}