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

package/dist/core/links/corpus.js

@@ -0,0 +1,104 @@
+/**
+ * WHICH documents loam reads links out of — the corpus, spelled once.
+ *
+ * Two readers need it and must not disagree. `commands/validate/links/` grades
+ * each target's own documents for `link.unresolved`; `core/glossary/backlinks.ts`
+ * reads the WHOLE fleet's, because "which documents use this term" is a question
+ * no single target can answer. A corpus that differed between them would report
+ * a term as unused while the very document citing it was being graded one target
+ * over.
+ *
+ * THE CORPUS IS EVERY AUTHORED MARKDOWN DOCUMENT, and the word doing the work is
+ * authored. `AGENTS.md` and the scaffolded `README.md` are excluded because loam
+ * WRITES them: a finding against generated prose names a defect its reader
+ * cannot fix by editing, since the next `loam init` restores it. Their links are
+ * loam's own problem, held on this side of the boundary by
+ * `test/docs-facts.test.ts` and `test/package-docs.test.ts`.
+ *
+ * ADRs AND RUNBOOKS ARE IN IT, and they are the reason the convention was
+ * written down at all: an ADR that supersedes another says which, by linking to
+ * it. They are also the first documents loam reads that it previously only
+ * counted, which is what `link.unreadable` exists for.
+ *
+ * `delta.likec4` IS NOT, and neither is any YAML: this is a markdown question.
+ * The one thing a delta holds that addresses another file — `metadata { op }` —
+ * has its own resolution and its own findings.
+ */
+import { featureCapabilityDeltas } from "../capabilities/delta/tree.js";
+import { readCapabilityTree } from "../capabilities/tree.js";
+import { featureGlossary } from "../glossary/delta.js";
+import { readGlossary } from "../glossary/tree.js";
+import { featurePaths, featureSpecPaths, fleetAdrsDir, servicePathsAt } from "../repo/paths.js";
+import { capabilityDocsDir, glossaryDir } from "../repo/authored/paths.js";
+import { featureSpecServices, listFeatures, listServices } from "../repo/repo.js";
+import { markdownFiles } from "../repo/tree/fs.js";
+/**
+ * One service's authored documents: the two requirement specs, the runbook, and
+ * every ADR. The specs cost nothing extra when a `FleetContext` is in play — it
+ * has already read both to parse their requirements, and the memo hands back the
+ * same text.
+ */
+export async function serviceDocuments(paths) {
+    return [paths.spec, paths.archSpec, paths.runbook, ...(await markdownFiles(paths.adrsDir))];
+}
+/**
+ * One feature's authored documents: the intent, each addressed service's two
+ * spec deltas, every ADR, and each capability delta document.
+ */
+export async function featureDocuments(featureDir, fleet) {
+    const paths = featurePaths(featureDir);
+    const docs = [paths.intent, ...(await markdownFiles(paths.adrsDir))];
+    for (const svc of await featureSpecServices(featureDir, fleet)) {
+        const spec = featureSpecPaths(featureDir, svc);
+        docs.push(spec.spec, spec.archSpec);
+    }
+    const capabilities = fleet === undefined ? await featureCapabilityDeltas(featureDir) : await fleet.featureCapabilityDeltas(featureDir);
+    docs.push(...capabilities.docs.map((d) => d.spec));
+    // The definitions this feature introduces. Their own links are graded like
+    // any other document's — a term that cites a term the feature is not adding
+    // is a broken join whether or not it has shipped yet.
+    docs.push(...(await featureGlossary(featureDir)).terms.map((t) => t.path));
+    return docs;
+}
+/**
+ * The documents that belong to no service and no feature: the fleet's own
+ * decision records, the living capability tree, and the glossary.
+ *
+ * Graded at fleet scope, so `validate --all` reports them once. A single-target
+ * run says nothing about them — the rule `permissions.unenforced` and
+ * `capability.invalid` already follow, and for the same reason: a finding about
+ * the fleet repeated on every service target is the report.
+ */
+export async function fleetDocuments(docsDir, fleet) {
+    const capabilities = fleet === undefined
+        ? await readCapabilityTree(capabilityDocsDir(docsDir))
+        : (await fleet.capabilities(docsDir)).tree;
+    const glossary = await readGlossary(glossaryDir(docsDir));
+    return [
+        ...(await markdownFiles(fleetAdrsDir(docsDir))),
+        ...capabilities.docs.map((d) => d.spec),
+        ...glossary.terms.map((t) => t.path),
+    ];
+}
+/**
+ * Every authored document in the repository — the union of the three above over
+ * every service and every in-flight feature.
+ *
+ * ARCHIVED FEATURES ARE OUT, and the omission is the point rather than an
+ * oversight. `features/archive/<FEAT>/` is the evolution history: its documents
+ * describe a change that already shipped, its links point at whatever the tree
+ * looked like then, and grading them would make every directory rename a
+ * retroactive error against a record nobody may edit. `listFeatures` excludes
+ * them by default, which is the same judgement one enumeration up.
+ */
+export async function allAuthoredDocuments(docsDir, fleet) {
+    const docs = await fleetDocuments(docsDir, fleet);
+    for (const service of await listServices(docsDir, fleet)) {
+        docs.push(...(await serviceDocuments(servicePathsAt(service.dir))));
+    }
+    for (const feature of await listFeatures(docsDir, {}, fleet)) {
+        docs.push(...(await featureDocuments(feature.dir, fleet)));
+    }
+    return docs;
+}
+//# sourceMappingURL=corpus.js.map

package/dist/core/links/corpus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"corpus.js","sourceRoot":"","sources":["../../../src/core/links/corpus.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * WHICH documents loam reads links out of — the corpus, spelled once.\n *\n * Two readers need it and must not disagree. `commands/validate/links/` grades\n * each target's own documents for `link.unresolved`; `core/glossary/backlinks.ts`\n * reads the WHOLE fleet's, because \"which documents use this term\" is a question\n * no single target can answer. A corpus that differed between them would report\n * a term as unused while the very document citing it was being graded one target\n * over.\n *\n * THE CORPUS IS EVERY AUTHORED MARKDOWN DOCUMENT, and the word doing the work is\n * authored. `AGENTS.md` and the scaffolded `README.md` are excluded because loam\n * WRITES them: a finding against generated prose names a defect its reader\n * cannot fix by editing, since the next `loam init` restores it. Their links are\n * loam's own problem, held on this side of the boundary by\n * `test/docs-facts.test.ts` and `test/package-docs.test.ts`.\n *\n * ADRs AND RUNBOOKS ARE IN IT, and they are the reason the convention was\n * written down at all: an ADR that supersedes another says which, by linking to\n * it. They are also the first documents loam reads that it previously only\n * counted, which is what `link.unreadable` exists for.\n *\n * `delta.likec4` IS NOT, and neither is any YAML: this is a markdown question.\n * The one thing a delta holds that addresses another file — `metadata { op }` —\n * has its own resolution and its own findings.\n */\nimport { featureCapabilityDeltas } from \"../capabilities/delta/tree.js\";\nimport { readCapabilityTree } from \"../capabilities/tree.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport { featureGlossary } from \"../glossary/delta.js\";\nimport { readGlossary } from \"../glossary/tree.js\";\nimport type { DocsDir, FeatureDir } from \"../kernel/ids/dirs.js\";\nimport { featurePaths, featureSpecPaths, fleetAdrsDir, servicePathsAt, type ServicePaths } from \"../repo/paths.js\";\nimport { capabilityDocsDir, glossaryDir } from \"../repo/authored/paths.js\";\nimport { featureSpecServices, listFeatures, listServices } from \"../repo/repo.js\";\nimport { markdownFiles } from \"../repo/tree/fs.js\";\n\n/**\n * One service's authored documents: the two requirement specs, the runbook, and\n * every ADR. The specs cost nothing extra when a `FleetContext` is in play — it\n * has already read both to parse their requirements, and the memo hands back the\n * same text.\n */\nexport async function serviceDocuments(paths: ServicePaths): Promise<string[]> {\n  return [paths.spec, paths.archSpec, paths.runbook, ...(await markdownFiles(paths.adrsDir))];\n}\n\n/**\n * One feature's authored documents: the intent, each addressed service's two\n * spec deltas, every ADR, and each capability delta document.\n */\nexport async function featureDocuments(featureDir: FeatureDir, fleet?: FleetContext): Promise<string[]> {\n  const paths = featurePaths(featureDir);\n  const docs = [paths.intent, ...(await markdownFiles(paths.adrsDir))];\n  for (const svc of await featureSpecServices(featureDir, fleet)) {\n    const spec = featureSpecPaths(featureDir, svc);\n    docs.push(spec.spec, spec.archSpec);\n  }\n  const capabilities =\n    fleet === undefined ? await featureCapabilityDeltas(featureDir) : await fleet.featureCapabilityDeltas(featureDir);\n  docs.push(...capabilities.docs.map((d) => d.spec));\n  // The definitions this feature introduces. Their own links are graded like\n  // any other document's — a term that cites a term the feature is not adding\n  // is a broken join whether or not it has shipped yet.\n  docs.push(...(await featureGlossary(featureDir)).terms.map((t) => t.path));\n  return docs;\n}\n\n/**\n * The documents that belong to no service and no feature: the fleet's own\n * decision records, the living capability tree, and the glossary.\n *\n * Graded at fleet scope, so `validate --all` reports them once. A single-target\n * run says nothing about them — the rule `permissions.unenforced` and\n * `capability.invalid` already follow, and for the same reason: a finding about\n * the fleet repeated on every service target is the report.\n */\nexport async function fleetDocuments(docsDir: DocsDir, fleet?: FleetContext): Promise<string[]> {\n  const capabilities =\n    fleet === undefined\n      ? await readCapabilityTree(capabilityDocsDir(docsDir))\n      : (await fleet.capabilities(docsDir)).tree;\n  const glossary = await readGlossary(glossaryDir(docsDir));\n  return [\n    ...(await markdownFiles(fleetAdrsDir(docsDir))),\n    ...capabilities.docs.map((d) => d.spec),\n    ...glossary.terms.map((t) => t.path),\n  ];\n}\n\n/**\n * Every authored document in the repository — the union of the three above over\n * every service and every in-flight feature.\n *\n * ARCHIVED FEATURES ARE OUT, and the omission is the point rather than an\n * oversight. `features/archive/<FEAT>/` is the evolution history: its documents\n * describe a change that already shipped, its links point at whatever the tree\n * looked like then, and grading them would make every directory rename a\n * retroactive error against a record nobody may edit. `listFeatures` excludes\n * them by default, which is the same judgement one enumeration up.\n */\nexport async function allAuthoredDocuments(docsDir: DocsDir, fleet?: FleetContext): Promise<string[]> {\n  const docs = await fleetDocuments(docsDir, fleet);\n  for (const service of await listServices(docsDir, fleet)) {\n    docs.push(...(await serviceDocuments(servicePathsAt(service.dir))));\n  }\n  for (const feature of await listFeatures(docsDir, {}, fleet)) {\n    docs.push(...(await featureDocuments(feature.dir, fleet)));\n  }\n  return docs;\n}\n"]}

package/dist/core/links/findings.js

@@ -0,0 +1,110 @@
+/**
+ * `link.unresolved` — a markdown link in an authored document whose target is
+ * not there, or is there under a different spelling.
+ *
+ * The convention this grades has been written down since the fleet-ADR work and
+ * said, in both `SCHEMA.md` and the generated `AGENTS.md`, that nothing
+ * validated it. This module is what makes that sentence false, and the reason
+ * the convention was chosen is the reason it can: the target of a standard
+ * markdown link is a real relative path, so "does this resolve" has a
+ * filesystem answer, where a wikilink would need Obsidian's
+ * shortest-unique-path search reimplemented — guessing, which loam does not do.
+ *
+ * ERROR, and the severity is the decision the maintainer took against the
+ * alternative of warning outside `glossary/`. A link is a join of the same kind
+ * as `Operations:` and `Covers:`, both of which error when they resolve to
+ * nothing; the fact that this one is written in prose changes who typed it, not
+ * whether it points at something. A fleet adopting loam with rotted links sees
+ * them on its first run — a user-visible widening of the same class as the two
+ * the use-case and business axes shipped, and recorded in CHANGELOG as one.
+ *
+ * ONE FINDING PER DOCUMENT, with every broken link in `details`. A document
+ * whose links have rotted is one editing session and one reviewer, not ten
+ * separate breaches, and per-link findings would let a single stale directory
+ * rename fill a `validate --all` report with the same fix restated.
+ *
+ * THE RESOLUTION IS EXPORTED SEPARATELY from the finding, because a second
+ * reader needs the other half of the answer: the glossary grades a term by who
+ * links TO it, which is this same walk read forwards instead of backwards.
+ */
+import { existsSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import { repoPath } from "../envelope/json.js";
+import { isPathInside } from "../kernel/path-safety.js";
+import { pathCaseIndex } from "./case.js";
+import { documentLinks } from "./parse.js";
+/**
+ * Every link in one document, resolved against the docs repo.
+ *
+ * TARGETS OUTSIDE THE DOCS REPO ARE NEITHER RESOLVED NOR BROKEN, and the
+ * exclusion is honesty rather than leniency. A docs repo is routinely checked
+ * out beside nothing else, so `../../payments-svc/README.md` is a path loam
+ * cannot answer for: the file's absence here is evidence about this checkout,
+ * not about the link. Only a target that stays inside `docsDir` gets a verdict,
+ * which is the same boundary every other reader in loam observes and the reason
+ * the finding below can afford to be an error at all.
+ *
+ * CASE COUNTS, and it must, because the alternative is a check that passes on
+ * the author's machine and fails where the work is read. `existsSync` is
+ * case-insensitive on Windows and macOS; GitHub's renderer and every Linux CI
+ * runner are not. So a resolving link is one that exists AND is spelled the way
+ * the filesystem stores it — and when it is not, `storedAs` carries the real
+ * name into the message, on every platform alike, so the diagnosis does not
+ * depend on which operating system ran the check.
+ */
+export function resolveLinks(doc, scope) {
+    const cases = scope.cases ?? pathCaseIndex();
+    const dir = dirname(doc.path);
+    const linkage = { resolved: [], broken: [] };
+    for (const link of documentLinks(doc.text)) {
+        const target = resolve(dir, link.path);
+        if (!isPathInside(scope.docsDir, target))
+            continue;
+        // The overlay is checked FIRST and without the spelling test: the file is
+        // not on disk, so there is no stored name to compare against, and the id it
+        // came from was a `readdir` entry in the feature's own tree.
+        if (scope.overlay?.has(resolve(target)) === true) {
+            linkage.resolved.push({ link, target });
+            continue;
+        }
+        if (existsSync(target) && cases.spelledExactly(scope.docsDir, target)) {
+            linkage.resolved.push({ link, target });
+            continue;
+        }
+        const storedAs = cases.storedAs(dirname(target), basename(target));
+        linkage.broken.push({ link, ...(storedAs === undefined ? {} : { storedAs }) });
+    }
+    return linkage;
+}
+/** The links in one document that resolve to nothing, as at most one finding. */
+export function unresolvedLinkFindings(doc, scope) {
+    const where = repoPath(scope.docsDir, doc.path);
+    const { broken } = resolveLinks(doc, scope);
+    if (broken.length === 0)
+        return [];
+    return [
+        {
+            severity: "error",
+            code: "link.unresolved",
+            ...(scope.subject === undefined ? {} : { subject: scope.subject }),
+            message: `${where}: ${broken.length} markdown link(s) resolve to nothing. ` +
+                "A link between documents here is a join — fix the path, or write the document it points at. " +
+                "Targets outside the docs repo and links to a heading (`#section`) are not graded.",
+            details: broken.map((one) => detail(where, one)),
+        },
+    ];
+}
+/**
+ * One broken link, spelled so the author can find it: the file and line first,
+ * then the link exactly as written. `raw` rather than the decoded path, because
+ * the decoded form is not the string that is in the document.
+ *
+ * The stored spelling is appended when the only thing wrong is case, because
+ * without it the message reads as a lie — the file the author is being told to
+ * write is already sitting beside the one they linked from.
+ */
+function detail(where, one) {
+    const line = `${where}:${one.link.line}: [${one.link.text}](${one.link.raw})`;
+    return one.storedAs === undefined ? line : `${line} — stored as '${one.storedAs}'`;
+}
+//# sourceMappingURL=findings.js.map

package/dist/core/links/findings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"findings.js","sourceRoot":"","sources":["../../../src/core/links/findings.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `link.unresolved` — a markdown link in an authored document whose target is\n * not there, or is there under a different spelling.\n *\n * The convention this grades has been written down since the fleet-ADR work and\n * said, in both `SCHEMA.md` and the generated `AGENTS.md`, that nothing\n * validated it. This module is what makes that sentence false, and the reason\n * the convention was chosen is the reason it can: the target of a standard\n * markdown link is a real relative path, so \"does this resolve\" has a\n * filesystem answer, where a wikilink would need Obsidian's\n * shortest-unique-path search reimplemented — guessing, which loam does not do.\n *\n * ERROR, and the severity is the decision the maintainer took against the\n * alternative of warning outside `glossary/`. A link is a join of the same kind\n * as `Operations:` and `Covers:`, both of which error when they resolve to\n * nothing; the fact that this one is written in prose changes who typed it, not\n * whether it points at something. A fleet adopting loam with rotted links sees\n * them on its first run — a user-visible widening of the same class as the two\n * the use-case and business axes shipped, and recorded in CHANGELOG as one.\n *\n * ONE FINDING PER DOCUMENT, with every broken link in `details`. A document\n * whose links have rotted is one editing session and one reviewer, not ten\n * separate breaches, and per-link findings would let a single stale directory\n * rename fill a `validate --all` report with the same fix restated.\n *\n * THE RESOLUTION IS EXPORTED SEPARATELY from the finding, because a second\n * reader needs the other half of the answer: the glossary grades a term by who\n * links TO it, which is this same walk read forwards instead of backwards.\n */\nimport { existsSync } from \"node:fs\";\nimport { basename, dirname, resolve } from \"node:path\";\nimport { repoPath } from \"../envelope/json.js\";\nimport { isPathInside } from \"../kernel/path-safety.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\nimport type { Finding } from \"../vocabulary/report.js\";\nimport { pathCaseIndex, type PathCaseIndex } from \"./case.js\";\nimport { documentLinks, type DocumentLink } from \"./parse.js\";\n\n/** One authored document, and the text somebody already read out of it. */\nexport interface LinkedDocument {\n  /** Absolute path of the document — the directory every relative target resolves against. */\n  path: string;\n  text: string;\n}\n\n/** What the finding is filed under, and the tree it may look inside. */\nexport interface LinkScope {\n  docsDir: DocsDir;\n  /** The service or feature the report is about; absent at fleet scope. */\n  subject?: string;\n  /**\n   * The directory-listing memo behind the case check, shared across a whole\n   * run by whoever owns the walk. Omitted, each call builds its own — correct,\n   * just not shared. Never a module-level cache: a listing that outlived one\n   * command would answer for a directory that has since changed.\n   */\n  cases?: PathCaseIndex;\n  /**\n   * Absolute paths that do not exist yet but WILL once an in-flight feature\n   * archives — today, the glossary terms that feature introduces.\n   *\n   * A feature cites the word it is adding at the word's FUTURE living path,\n   * because that is where the link has to point once the change lands; citing\n   * the delta's own path would resolve now and rot on the day it ships. Without\n   * this set, the axis would refuse its own headline case — which is exactly\n   * the overlay the capability axis had to add to `Realizes:` after shipping\n   * without one.\n   */\n  overlay?: ReadonlySet<string>;\n}\n\n/** A link that points at a real file inside the docs repo, and the file it points at. */\nexport interface ResolvedLink {\n  link: DocumentLink;\n  /** The absolute path the link names, as `node:path` resolves it. */\n  target: string;\n}\n\n/** One document's links, split by whether the docs repo answers for them. */\nexport interface DocumentLinkage {\n  resolved: ResolvedLink[];\n  /** Links inside the docs repo that name nothing — with the stored spelling, where there is one. */\n  broken: Array<{ link: DocumentLink; storedAs?: string }>;\n}\n\n/**\n * Every link in one document, resolved against the docs repo.\n *\n * TARGETS OUTSIDE THE DOCS REPO ARE NEITHER RESOLVED NOR BROKEN, and the\n * exclusion is honesty rather than leniency. A docs repo is routinely checked\n * out beside nothing else, so `../../payments-svc/README.md` is a path loam\n * cannot answer for: the file's absence here is evidence about this checkout,\n * not about the link. Only a target that stays inside `docsDir` gets a verdict,\n * which is the same boundary every other reader in loam observes and the reason\n * the finding below can afford to be an error at all.\n *\n * CASE COUNTS, and it must, because the alternative is a check that passes on\n * the author's machine and fails where the work is read. `existsSync` is\n * case-insensitive on Windows and macOS; GitHub's renderer and every Linux CI\n * runner are not. So a resolving link is one that exists AND is spelled the way\n * the filesystem stores it — and when it is not, `storedAs` carries the real\n * name into the message, on every platform alike, so the diagnosis does not\n * depend on which operating system ran the check.\n */\nexport function resolveLinks(doc: LinkedDocument, scope: LinkScope): DocumentLinkage {\n  const cases = scope.cases ?? pathCaseIndex();\n  const dir = dirname(doc.path);\n  const linkage: DocumentLinkage = { resolved: [], broken: [] };\n  for (const link of documentLinks(doc.text)) {\n    const target = resolve(dir, link.path);\n    if (!isPathInside(scope.docsDir, target)) continue;\n    // The overlay is checked FIRST and without the spelling test: the file is\n    // not on disk, so there is no stored name to compare against, and the id it\n    // came from was a `readdir` entry in the feature's own tree.\n    if (scope.overlay?.has(resolve(target)) === true) {\n      linkage.resolved.push({ link, target });\n      continue;\n    }\n    if (existsSync(target) && cases.spelledExactly(scope.docsDir, target)) {\n      linkage.resolved.push({ link, target });\n      continue;\n    }\n    const storedAs = cases.storedAs(dirname(target), basename(target));\n    linkage.broken.push({ link, ...(storedAs === undefined ? {} : { storedAs }) });\n  }\n  return linkage;\n}\n\n/** The links in one document that resolve to nothing, as at most one finding. */\nexport function unresolvedLinkFindings(doc: LinkedDocument, scope: LinkScope): Finding[] {\n  const where = repoPath(scope.docsDir, doc.path);\n  const { broken } = resolveLinks(doc, scope);\n  if (broken.length === 0) return [];\n  return [\n    {\n      severity: \"error\",\n      code: \"link.unresolved\",\n      ...(scope.subject === undefined ? {} : { subject: scope.subject }),\n      message:\n        `${where}: ${broken.length} markdown link(s) resolve to nothing. ` +\n        \"A link between documents here is a join — fix the path, or write the document it points at. \" +\n        \"Targets outside the docs repo and links to a heading (`#section`) are not graded.\",\n      details: broken.map((one) => detail(where, one)),\n    },\n  ];\n}\n\n/**\n * One broken link, spelled so the author can find it: the file and line first,\n * then the link exactly as written. `raw` rather than the decoded path, because\n * the decoded form is not the string that is in the document.\n *\n * The stored spelling is appended when the only thing wrong is case, because\n * without it the message reads as a lie — the file the author is being told to\n * write is already sitting beside the one they linked from.\n */\nfunction detail(where: string, one: { link: DocumentLink; storedAs?: string }): string {\n  const line = `${where}:${one.link.line}: [${one.link.text}](${one.link.raw})`;\n  return one.storedAs === undefined ? line : `${line} — stored as '${one.storedAs}'`;\n}\n"]}

package/dist/core/links/parse.js

@@ -0,0 +1,236 @@
+/**
+ * Every markdown link a document writes, as data.
+ *
+ * A link between documents in a docs repo is a JOIN, not decoration — a
+ * requirement that names a domain term points at that term's definition, and an
+ * ADR that supersedes another says which. `SCHEMA.md` and the generated
+ * `AGENTS.md` have stated the convention (standard markdown links, relative
+ * path targets) since the fleet-ADR work; this module is what finally reads
+ * one, so `./findings.ts` can answer the only question the convention was
+ * chosen for: does the target exist.
+ *
+ * WHY A PARSER RATHER THAN A REGEX AT THE CALL SITE. Two classes of false
+ * positive make the naive `\[.*\]\(.*\)` unusable on the documents loam owns,
+ * and both occur in loam's OWN generated prose. A fenced block is where a
+ * document SHOWS the convention — the `AGENTS.md` section that teaches the link
+ * format contains a link nobody wrote to be followed — and an inline code span
+ * is where prose quotes a path. Both must read as text. The fence rule is the
+ * one `core/document/parse.ts` already applies to headings, and it is imported
+ * rather than restated for the reason that module gives about its own sampler:
+ * two readers disagreeing about what a fence encloses prescribe a document no
+ * author can satisfy.
+ */
+import { relative, resolve, sep } from "node:path";
+import { fenceTracker } from "../kernel/fences.js";
+/**
+ * Inline links and images: `[text](target)`, `![alt](target)`,
+ * `[text](<target with spaces>)`, `[text](target "title")`.
+ *
+ * The target alternation takes `<...>` first so an angle-bracketed path
+ * containing spaces stays one token; the bare form stops at whitespace or `)`,
+ * which gives up on the balanced-parens spelling markdown also allows
+ * (`[x](a(1).md)`). That is a deliberate under-read: it costs a link nobody
+ * writes, where over-reading would swallow the rest of a sentence and report a
+ * target no author would recognise.
+ */
+const INLINE_RE = /!?\[([^\]]*)\]\(\s*(<[^>\n]*>|[^\s)]*)(?:\s+(?:"[^"]*"|'[^']*'|\([^)]*\)))?\s*\)/gd;
+/**
+ * A reference DEFINITION — `[label]: target "title"` on its own line. Included
+ * because the target is the same join written in a different place: a document
+ * that collects its links at the bottom is following the convention, and a
+ * reader that only saw inline links would grade it as having none.
+ */
+const DEFINITION_RE = /^ {0,3}\[([^\]]+)\]:\s*(<[^>\n]*>|\S+)/d;
+/**
+ * Code spans, blanked before matching. `\`[a](b)\`` is prose ABOUT a link and
+ * resolving it would convict a document for explaining the convention. Blanked
+ * to spaces rather than removed so every column after it — and therefore any
+ * real link later on the same line — keeps its position.
+ */
+const CODE_SPAN_RE = /(`+)(?:[^`]|(?!\1)`)*\1/g;
+/**
+ * Every link in `md`, in document order.
+ *
+ * The whole document is scanned, frontmatter included: a YAML `see: [x](y.md)`
+ * is not a link loam wrote a field for, and the alternative — teaching this
+ * module where frontmatter ends — would make it read the one part of a document
+ * loam's own doctrine says is structured. A link that resolves is a link that
+ * resolves wherever it is written.
+ */
+export function documentLinks(md) {
+    const fenced = fenceTracker();
+    const out = [];
+    md.split(/\r?\n/).forEach((rawLine, i) => {
+        if (fenced(rawLine))
+            return;
+        const line = rawLine.replace(CODE_SPAN_RE, (m) => " ".repeat(m.length));
+        const definition = DEFINITION_RE.exec(line);
+        if (definition) {
+            push(out, definition[2], definition[1], i + 1);
+            return;
+        }
+        INLINE_RE.lastIndex = 0;
+        for (let m = INLINE_RE.exec(line); m !== null; m = INLINE_RE.exec(line)) {
+            push(out, m[2], m[1], i + 1);
+        }
+    });
+    return out;
+}
+/**
+ * Record one link, unless its target is not a path this repository can answer
+ * for. Four exclusions, each of them a question with no filesystem answer
+ * rather than a link loam declines to grade:
+ *
+ * - an EMPTY target (`[text]()`) addresses nothing;
+ * - a SCHEME (`https:`, `mailto:`, and a Windows `C:` drive with it) addresses
+ *   something outside this repository;
+ * - a ROOT-relative or protocol-relative target (`/x`, `//host/x`) is resolved
+ *   by whatever renders the document — a site root, not the file's directory —
+ *   so loam does not know what it points at;
+ * - a PURE fragment (`#section`) addresses this same document, and grading it
+ *   means resolving heading anchors, which is a different question from "does
+ *   this file exist".
+ *
+ * The last two are DEFENSIVE rather than decisive, and a mutation run says so:
+ * removing either leaves every test green, because a pure fragment leaves an
+ * empty path and a site-root target resolves outside the docs repo, where
+ * `./findings.ts` declines to answer anyway. They are kept because the reason
+ * differs from that boundary's — loam is not silent about these because they
+ * are elsewhere, it is silent because it does not know where they are — and a
+ * later reader deleting them as dead would be removing an intention, not a
+ * branch.
+ */
+function push(out, target, text, line) {
+    const raw = target.startsWith("<") && target.endsWith(">") ? target.slice(1, -1) : target;
+    if (raw === "" || raw.startsWith("#") || raw.startsWith("/"))
+        return;
+    if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(raw))
+        return;
+    const path = decodePath(raw.split("#")[0]);
+    if (path === "")
+        return;
+    out.push({ raw, path, text, line });
+}
+/**
+ * Percent-decode a link target, or keep it verbatim when it does not decode.
+ *
+ * `[Order line](order%20line.md)` is how every editor writes a path holding a
+ * space, so a resolver that skipped this step would report the one spelling
+ * authors do not type by hand. `decodeURIComponent` throws on a lone `%` — a
+ * literal percent in a filename is legal and rarer than the escape — and the
+ * honest answer there is the string as written, which then resolves or does not
+ * on its own terms.
+ */
+function decodePath(raw) {
+    try {
+        return decodeURIComponent(raw);
+    }
+    catch {
+        return raw;
+    }
+}
+/**
+ * Re-express every relative link in `md` from a new base directory — the merge's
+ * half of the link convention.
+ *
+ * THE DEFECT THIS CLOSES is structural and predates the glossary. A feature's
+ * `specs/<svc>/spec.md` sits four directories below the docs root; the living
+ * `services/<svc>/spec.md` it merges into sits two. `loam archive` copies a
+ * requirement's text verbatim, so `[Order](../../../../glossary/order.md)` —
+ * correct where it was written, and clickable in the pull request that reviewed
+ * it — lands in the living document pointing two directories above the
+ * repository. The same is true of a delta requirement citing an ADR, which has
+ * been possible since before this module existed.
+ *
+ * REWRITING IS THE ONLY ANSWER THAT KEEPS BOTH PROPERTIES. The alternative
+ * considered was to have authors write the link relative to where the text will
+ * END UP, leaving loam to touch nothing — but that link does not resolve in the
+ * delta, and "it renders as a link in pull-request review, which is where these
+ * documents are actually read" is the convention's own first argument. So the
+ * author writes what is true where they write it, and the merge makes it true
+ * where it lands. The target is unchanged: only the route to it is.
+ *
+ * It is a positional rewrite, never a re-render: the matched target's own span
+ * is replaced and every other byte of the line — the link text, the title, the
+ * prose around it — is left exactly as written.
+ */
+export function rebaseLinks(md, move) {
+    const from = resolve(move.from);
+    const to = resolve(move.to);
+    if (from === to)
+        return md;
+    const fenced = fenceTracker();
+    // `split` with a capturing group keeps the separators, so a document's own
+    // mixture of CRLF and LF survives a rewrite that touches neither.
+    const parts = md.split(/(\r?\n)/);
+    for (let i = 0; i < parts.length; i += 2) {
+        const rawLine = parts[i];
+        if (fenced(rawLine))
+            continue;
+        parts[i] = rebaseLine(rawLine, from, to);
+    }
+    return parts.join("");
+}
+/** One line's links re-expressed, right to left so earlier spans keep their offsets. */
+function rebaseLine(rawLine, from, to) {
+    const blanked = rawLine.replace(CODE_SPAN_RE, (m) => " ".repeat(m.length));
+    const spans = [];
+    const collect = (m) => {
+        const at = m.indices?.[2];
+        if (at === undefined)
+            return;
+        const rebased = rebaseTarget(m[2], from, to);
+        if (rebased !== null)
+            spans.push([at[0], at[1], rebased]);
+    };
+    const definition = DEFINITION_RE.exec(blanked);
+    if (definition)
+        collect(definition);
+    else {
+        INLINE_RE.lastIndex = 0;
+        for (let m = INLINE_RE.exec(blanked); m !== null; m = INLINE_RE.exec(blanked))
+            collect(m);
+    }
+    let out = rawLine;
+    for (const [start, end, replacement] of spans.reverse()) {
+        out = out.slice(0, start) + replacement + out.slice(end);
+    }
+    return out;
+}
+/**
+ * One target, re-expressed from `to` instead of `from`, or null when there is
+ * nothing to re-express.
+ *
+ * The exclusions are `push`'s exactly — an absolute URL, a site-root path and a
+ * bare fragment mean the same thing from every directory — and the ANGLE-BRACKET
+ * and PERCENT-ESCAPE forms are preserved rather than normalised: a rewrite that
+ * silently changed `<a b.md>` into `a%20b.md` would be editing the author's
+ * spelling under cover of moving their file.
+ */
+function rebaseTarget(target, from, to) {
+    const angled = target.startsWith("<") && target.endsWith(">");
+    const raw = angled ? target.slice(1, -1) : target;
+    if (raw === "" || raw.startsWith("#") || raw.startsWith("/"))
+        return null;
+    if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(raw))
+        return null;
+    const hash = raw.indexOf("#");
+    const pathPart = hash === -1 ? raw : raw.slice(0, hash);
+    const fragment = hash === -1 ? "" : raw.slice(hash);
+    if (pathPart === "")
+        return null;
+    const encoded = pathPart.includes("%");
+    let rebased = relative(to, resolve(from, decodePath(pathPart))).split(sep).join("/");
+    // `relative` returns a bare name for a sibling, which markdown reads as a
+    // path relative to the file anyway — but `./` is what an author writes and
+    // what keeps the link distinguishable from a reference label.
+    if (rebased !== "" && !rebased.startsWith("."))
+        rebased = `./${rebased}`;
+    if (rebased === "")
+        return null;
+    if (!angled && (encoded || rebased.includes(" ")))
+        rebased = rebased.split(" ").join("%20");
+    const rewritten = rebased + fragment;
+    return angled ? `<${rewritten}>` : rewritten;
+}
+//# sourceMappingURL=parse.js.map

package/dist/core/links/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../../src/core/links/parse.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Every markdown link a document writes, as data.\n *\n * A link between documents in a docs repo is a JOIN, not decoration — a\n * requirement that names a domain term points at that term's definition, and an\n * ADR that supersedes another says which. `SCHEMA.md` and the generated\n * `AGENTS.md` have stated the convention (standard markdown links, relative\n * path targets) since the fleet-ADR work; this module is what finally reads\n * one, so `./findings.ts` can answer the only question the convention was\n * chosen for: does the target exist.\n *\n * WHY A PARSER RATHER THAN A REGEX AT THE CALL SITE. Two classes of false\n * positive make the naive `\\[.*\\]\\(.*\\)` unusable on the documents loam owns,\n * and both occur in loam's OWN generated prose. A fenced block is where a\n * document SHOWS the convention — the `AGENTS.md` section that teaches the link\n * format contains a link nobody wrote to be followed — and an inline code span\n * is where prose quotes a path. Both must read as text. The fence rule is the\n * one `core/document/parse.ts` already applies to headings, and it is imported\n * rather than restated for the reason that module gives about its own sampler:\n * two readers disagreeing about what a fence encloses prescribe a document no\n * author can satisfy.\n */\nimport { relative, resolve, sep } from \"node:path\";\nimport { fenceTracker } from \"../kernel/fences.js\";\n\n/** One link written in a markdown document. */\nexport interface DocumentLink {\n  /** The target exactly as written, angle brackets stripped, fragment included. */\n  raw: string;\n  /**\n   * The FILE half — `raw` with any `#fragment` removed and percent-escapes\n   * decoded. This is what resolves against the filesystem; `raw` is what the\n   * finding quotes back, because that is the string the author has to find.\n   */\n  path: string;\n  /** The link text, or the reference label for a definition. Quoted in the finding. */\n  text: string;\n  /** 1-based line the link was written on. */\n  line: number;\n}\n\n/**\n * Inline links and images: `[text](target)`, `![alt](target)`,\n * `[text](<target with spaces>)`, `[text](target \"title\")`.\n *\n * The target alternation takes `<...>` first so an angle-bracketed path\n * containing spaces stays one token; the bare form stops at whitespace or `)`,\n * which gives up on the balanced-parens spelling markdown also allows\n * (`[x](a(1).md)`). That is a deliberate under-read: it costs a link nobody\n * writes, where over-reading would swallow the rest of a sentence and report a\n * target no author would recognise.\n */\nconst INLINE_RE = /!?\\[([^\\]]*)\\]\\(\\s*(<[^>\\n]*>|[^\\s)]*)(?:\\s+(?:\"[^\"]*\"|'[^']*'|\\([^)]*\\)))?\\s*\\)/gd;\n\n/**\n * A reference DEFINITION — `[label]: target \"title\"` on its own line. Included\n * because the target is the same join written in a different place: a document\n * that collects its links at the bottom is following the convention, and a\n * reader that only saw inline links would grade it as having none.\n */\nconst DEFINITION_RE = /^ {0,3}\\[([^\\]]+)\\]:\\s*(<[^>\\n]*>|\\S+)/d;\n\n/**\n * Code spans, blanked before matching. `\\`[a](b)\\`` is prose ABOUT a link and\n * resolving it would convict a document for explaining the convention. Blanked\n * to spaces rather than removed so every column after it — and therefore any\n * real link later on the same line — keeps its position.\n */\nconst CODE_SPAN_RE = /(`+)(?:[^`]|(?!\\1)`)*\\1/g;\n\n/**\n * Every link in `md`, in document order.\n *\n * The whole document is scanned, frontmatter included: a YAML `see: [x](y.md)`\n * is not a link loam wrote a field for, and the alternative — teaching this\n * module where frontmatter ends — would make it read the one part of a document\n * loam's own doctrine says is structured. A link that resolves is a link that\n * resolves wherever it is written.\n */\nexport function documentLinks(md: string): DocumentLink[] {\n  const fenced = fenceTracker();\n  const out: DocumentLink[] = [];\n  md.split(/\\r?\\n/).forEach((rawLine, i) => {\n    if (fenced(rawLine)) return;\n    const line = rawLine.replace(CODE_SPAN_RE, (m) => \" \".repeat(m.length));\n    const definition = DEFINITION_RE.exec(line);\n    if (definition) {\n      push(out, definition[2]!, definition[1]!, i + 1);\n      return;\n    }\n    INLINE_RE.lastIndex = 0;\n    for (let m = INLINE_RE.exec(line); m !== null; m = INLINE_RE.exec(line)) {\n      push(out, m[2]!, m[1]!, i + 1);\n    }\n  });\n  return out;\n}\n\n/**\n * Record one link, unless its target is not a path this repository can answer\n * for. Four exclusions, each of them a question with no filesystem answer\n * rather than a link loam declines to grade:\n *\n * - an EMPTY target (`[text]()`) addresses nothing;\n * - a SCHEME (`https:`, `mailto:`, and a Windows `C:` drive with it) addresses\n *   something outside this repository;\n * - a ROOT-relative or protocol-relative target (`/x`, `//host/x`) is resolved\n *   by whatever renders the document — a site root, not the file's directory —\n *   so loam does not know what it points at;\n * - a PURE fragment (`#section`) addresses this same document, and grading it\n *   means resolving heading anchors, which is a different question from \"does\n *   this file exist\".\n *\n * The last two are DEFENSIVE rather than decisive, and a mutation run says so:\n * removing either leaves every test green, because a pure fragment leaves an\n * empty path and a site-root target resolves outside the docs repo, where\n * `./findings.ts` declines to answer anyway. They are kept because the reason\n * differs from that boundary's — loam is not silent about these because they\n * are elsewhere, it is silent because it does not know where they are — and a\n * later reader deleting them as dead would be removing an intention, not a\n * branch.\n */\nfunction push(out: DocumentLink[], target: string, text: string, line: number): void {\n  const raw = target.startsWith(\"<\") && target.endsWith(\">\") ? target.slice(1, -1) : target;\n  if (raw === \"\" || raw.startsWith(\"#\") || raw.startsWith(\"/\")) return;\n  if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(raw)) return;\n  const path = decodePath(raw.split(\"#\")[0]!);\n  if (path === \"\") return;\n  out.push({ raw, path, text, line });\n}\n\n/**\n * Percent-decode a link target, or keep it verbatim when it does not decode.\n *\n * `[Order line](order%20line.md)` is how every editor writes a path holding a\n * space, so a resolver that skipped this step would report the one spelling\n * authors do not type by hand. `decodeURIComponent` throws on a lone `%` — a\n * literal percent in a filename is legal and rarer than the escape — and the\n * honest answer there is the string as written, which then resolves or does not\n * on its own terms.\n */\nfunction decodePath(raw: string): string {\n  try {\n    return decodeURIComponent(raw);\n  } catch {\n    return raw;\n  }\n}\n\n/**\n * Re-express every relative link in `md` from a new base directory — the merge's\n * half of the link convention.\n *\n * THE DEFECT THIS CLOSES is structural and predates the glossary. A feature's\n * `specs/<svc>/spec.md` sits four directories below the docs root; the living\n * `services/<svc>/spec.md` it merges into sits two. `loam archive` copies a\n * requirement's text verbatim, so `[Order](../../../../glossary/order.md)` —\n * correct where it was written, and clickable in the pull request that reviewed\n * it — lands in the living document pointing two directories above the\n * repository. The same is true of a delta requirement citing an ADR, which has\n * been possible since before this module existed.\n *\n * REWRITING IS THE ONLY ANSWER THAT KEEPS BOTH PROPERTIES. The alternative\n * considered was to have authors write the link relative to where the text will\n * END UP, leaving loam to touch nothing — but that link does not resolve in the\n * delta, and \"it renders as a link in pull-request review, which is where these\n * documents are actually read\" is the convention's own first argument. So the\n * author writes what is true where they write it, and the merge makes it true\n * where it lands. The target is unchanged: only the route to it is.\n *\n * It is a positional rewrite, never a re-render: the matched target's own span\n * is replaced and every other byte of the line — the link text, the title, the\n * prose around it — is left exactly as written.\n */\nexport function rebaseLinks(md: string, move: { from: string; to: string }): string {\n  const from = resolve(move.from);\n  const to = resolve(move.to);\n  if (from === to) return md;\n  const fenced = fenceTracker();\n  // `split` with a capturing group keeps the separators, so a document's own\n  // mixture of CRLF and LF survives a rewrite that touches neither.\n  const parts = md.split(/(\\r?\\n)/);\n  for (let i = 0; i < parts.length; i += 2) {\n    const rawLine = parts[i]!;\n    if (fenced(rawLine)) continue;\n    parts[i] = rebaseLine(rawLine, from, to);\n  }\n  return parts.join(\"\");\n}\n\n/** One line's links re-expressed, right to left so earlier spans keep their offsets. */\nfunction rebaseLine(rawLine: string, from: string, to: string): string {\n  const blanked = rawLine.replace(CODE_SPAN_RE, (m) => \" \".repeat(m.length));\n  const spans: Array<[number, number, string]> = [];\n  const collect = (m: RegExpExecArray): void => {\n    const at = m.indices?.[2];\n    if (at === undefined) return;\n    const rebased = rebaseTarget(m[2]!, from, to);\n    if (rebased !== null) spans.push([at[0], at[1], rebased]);\n  };\n  const definition = DEFINITION_RE.exec(blanked);\n  if (definition) collect(definition);\n  else {\n    INLINE_RE.lastIndex = 0;\n    for (let m = INLINE_RE.exec(blanked); m !== null; m = INLINE_RE.exec(blanked)) collect(m);\n  }\n  let out = rawLine;\n  for (const [start, end, replacement] of spans.reverse()) {\n    out = out.slice(0, start) + replacement + out.slice(end);\n  }\n  return out;\n}\n\n/**\n * One target, re-expressed from `to` instead of `from`, or null when there is\n * nothing to re-express.\n *\n * The exclusions are `push`'s exactly — an absolute URL, a site-root path and a\n * bare fragment mean the same thing from every directory — and the ANGLE-BRACKET\n * and PERCENT-ESCAPE forms are preserved rather than normalised: a rewrite that\n * silently changed `<a b.md>` into `a%20b.md` would be editing the author's\n * spelling under cover of moving their file.\n */\nfunction rebaseTarget(target: string, from: string, to: string): string | null {\n  const angled = target.startsWith(\"<\") && target.endsWith(\">\");\n  const raw = angled ? target.slice(1, -1) : target;\n  if (raw === \"\" || raw.startsWith(\"#\") || raw.startsWith(\"/\")) return null;\n  if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(raw)) return null;\n  const hash = raw.indexOf(\"#\");\n  const pathPart = hash === -1 ? raw : raw.slice(0, hash);\n  const fragment = hash === -1 ? \"\" : raw.slice(hash);\n  if (pathPart === \"\") return null;\n  const encoded = pathPart.includes(\"%\");\n  let rebased = relative(to, resolve(from, decodePath(pathPart))).split(sep).join(\"/\");\n  // `relative` returns a bare name for a sibling, which markdown reads as a\n  // path relative to the file anyway — but `./` is what an author writes and\n  // what keeps the link distinguishable from a reference label.\n  if (rebased !== \"\" && !rebased.startsWith(\".\")) rebased = `./${rebased}`;\n  if (rebased === \"\") return null;\n  if (!angled && (encoded || rebased.includes(\" \"))) rebased = rebased.split(\" \").join(\"%20\");\n  const rewritten = rebased + fragment;\n  return angled ? `<${rewritten}>` : rewritten;\n}\n"]}

package/dist/core/mcp/argv.js

@@ -0,0 +1,111 @@
+/**
+ * A string value that argv would read as a flag is refused before any command
+ * sees it: {"target": "--type"} must not become a parsed option. Commander
+ * cannot make this distinction after the fact — by then the token IS a flag —
+ * so the boundary is here, on every string that crosses, array members
+ * included. No shell is ever involved, so this is the only smuggling path.
+ */
+function smuggled(property, value) {
+    return value.startsWith("-")
+        ? `argument '${property}' value '${value}' begins with '-' — a value argv would read as a flag is refused`
+        : null;
+}
+/** One string value checked for type and smuggling. */
+function checkedString(property, value) {
+    if (typeof value !== "string")
+        return { ok: false, problem: `argument '${property}' must be a string` };
+    const bad = smuggled(property, value);
+    return bad === null ? { ok: true, tokens: [value] } : { ok: false, problem: bad };
+}
+/** An array value checked member by member — rebuilt, not cast, so the claim is earned. */
+function checkedStrings(property, value) {
+    if (!Array.isArray(value))
+        return { ok: false, problem: `argument '${property}' must be an array of strings` };
+    const tokens = [];
+    for (const entry of value) {
+        const checked = checkedString(property, entry);
+        if (!checked.ok)
+            return checked;
+        tokens.push(...checked.tokens);
+    }
+    return { ok: true, tokens };
+}
+function positionalTokens(tool, args) {
+    const tokens = [];
+    for (const positional of tool.positionals) {
+        const value = args[positional.property];
+        if (value === undefined) {
+            if (positional.required)
+                return { ok: false, problem: `required argument '${positional.property}' is missing` };
+            continue;
+        }
+        const checked = positional.variadic
+            ? checkedStrings(positional.property, value)
+            : checkedString(positional.property, value);
+        if (!checked.ok)
+            return checked;
+        tokens.push(...checked.tokens);
+    }
+    return { ok: true, tokens };
+}
+function flagTokens(tool, args) {
+    const tokens = [];
+    for (const flag of tool.flags) {
+        const value = args[flag.property];
+        if (value === undefined) {
+            // The same refusal absent required positionals get: the client learns
+            // "-32602 missing argument", not an invalid-option envelope after the
+            // command already refused.
+            if (flag.required === true)
+                return { ok: false, problem: `required argument '${flag.property}' is missing` };
+            continue;
+        }
+        if (flag.kind === "boolean") {
+            if (typeof value !== "boolean")
+                return { ok: false, problem: `argument '${flag.property}' must be a boolean` };
+            if (value)
+                tokens.push(flag.flag);
+            continue;
+        }
+        const checked = flag.kind === "strings"
+            ? checkedStrings(flag.property, value)
+            : checkedString(flag.property, value);
+        if (!checked.ok)
+            return checked;
+        // A repeatable flag repeats per value; a single-valued one appears once.
+        for (const token of checked.tokens)
+            tokens.push(flag.flag, token);
+    }
+    return { ok: true, tokens };
+}
+/**
+ * The argv for one tool call — or the invalid-params problem that stops it.
+ * `--json` is always appended: the envelope is the tool-result contract, and
+ * a client cannot opt out of it into the human rendering. Unknown argument
+ * names refuse rather than vanish — the schema says additionalProperties
+ * false, and a server that enforced that only in the schema would silently
+ * drop the typo'd argument of any client that skipped validation.
+ */
+export function toArgv(tool, args) {
+    const known = new Set([
+        ...tool.positionals.map((p) => p.property),
+        ...tool.flags.map((f) => f.property),
+    ]);
+    for (const property of Object.keys(args)) {
+        if (!known.has(property)) {
+            const allowed = known.size === 0 ? "no arguments" : [...known].join(", ");
+            return { ok: false, problem: `unknown argument '${property}' for ${tool.name} — expected ${allowed}` };
+        }
+    }
+    const positionals = positionalTokens(tool, args);
+    if (!positionals.ok)
+        return { ok: false, problem: positionals.problem };
+    const flags = flagTokens(tool, args);
+    if (!flags.ok)
+        return { ok: false, problem: flags.problem };
+    return {
+        ok: true,
+        argv: [tool.command, ...positionals.tokens, ...flags.tokens, ...(tool.fixed ?? []), "--json"],
+    };
+}
+//# sourceMappingURL=argv.js.map