phronesis 1.0.0

package/vendor/core/src/workspace-scan.js

@@ -0,0 +1,125 @@
+// Workspace scan — the single source for "what is a typed object in a Phronesis
+// installation, and how do we find and read it." Shared by `phronesis validate`
+// (core-0004 / T2.1) and the link index + walk (core-0005 / T2.3); extracted to
+// packages/core (core-0007) so the action types (T2.2) get the same discovery.
+//
+// These three primitives encode the drift-prone half of the ontology contract — file
+// discovery, frontmatter splitting, and path→context (which folder means which layer /
+// type-dir). Keeping them in one module is what lets the validator and the link index
+// never disagree about what counts as an object or where a link target resolves.
+
+import { join, relative, basename, sep } from 'node:path';
+import { readdir, readFile } from 'node:fs/promises';
+import yaml from 'js-yaml';
+
+// THE answer to "where does a frontmatter block start and end" — one regex, two
+// consumers (the validator's splitFrontmatter and the RMW writers' splitObjectSource).
+// A second regex answering the same structural question is drift waiting to fire: the
+// core-0009 adversarial review reproduced validator-green files (a `--- ` closing fence
+// with a trailing space; an inner `--- ` line) that a stricter sibling regex refused or
+// mis-split. The closing fence tolerates same-line trailing whitespace and consumes
+// exactly ONE newline, so a body's leading blank line stays with the body (the RMW
+// writers carry the body over byte-for-byte).
+const FRONTMATTER_BLOCK_RE = /^---\r?\n([\s\S]*?)\r?\n---[^\S\r\n]*(?:\r?\n|$)/;
+
+export function matchFrontmatterBlock(content) {
+  return content.match(FRONTMATTER_BLOCK_RE);
+}
+
+// Split a leading `---\n…\n---` YAML frontmatter block. Returns the YAML source, or
+// null if the file has no frontmatter block.
+export function splitFrontmatter(content) {
+  const m = matchFrontmatterBlock(content);
+  return m ? m[1] : null;
+}
+
+// Read + parse one typed-object file into { rel, ctx, fm, body }, or null for anything
+// that is not a parseable typed object (no frontmatter, broken YAML, non-object YAML,
+// not an object path). ONE parse implementation for every consumer that turns a file
+// into an object record — the link index's disk pass and the search snapshot
+// (core-0014) both ride this; a re-typed sibling parse (its own yaml options, its own
+// shape checks) is the same drift class as a re-typed frontmatter regex (the core-0009
+// lesson, one level up).
+export async function readObjectRecord(root, rel) {
+  const ctx = contextFor(rel);
+  if (!ctx) return null;
+  let content;
+  try {
+    content = await readFile(join(root, rel), 'utf8');
+  } catch {
+    return null; // vanished mid-scan — the next pass sees the final state
+  }
+  const m = matchFrontmatterBlock(content);
+  if (!m) return null;
+  let fm;
+  try {
+    fm = yaml.load(m[1], { schema: yaml.JSON_SCHEMA });
+  } catch {
+    return null;
+  }
+  if (fm === null || typeof fm !== 'object' || Array.isArray(fm)) return null;
+  return { rel, ctx, fm, body: content.slice(m[0].length) };
+}
+
+// All *.md files under `root` (recursive), as install-relative paths. A missing dir
+// yields nothing (a fresh install may not have every layer populated yet).
+export async function walkMarkdown(installRoot, root) {
+  const out = [];
+  let entries;
+  try {
+    entries = await readdir(root, { withFileTypes: true });
+  } catch {
+    return out; // dir absent — nothing to walk
+  }
+  for (const e of entries) {
+    const abs = join(root, e.name);
+    if (e.isDirectory()) out.push(...(await walkMarkdown(installRoot, abs)));
+    else if (e.isFile() && e.name.endsWith('.md')) out.push(relative(installRoot, abs));
+  }
+  return out;
+}
+
+// Build the typed-object context for a file from its install-relative path.
+// Domain objects: domains/{slug}/compiled/{typeDir}/…/{name}.md. Codex objects:
+// codex/{personal|seed}/…/{name}.md (codex/INDEX.md is the map, not an object).
+// Returns null for anything that is not a typed object.
+export function contextFor(relPath) {
+  const parts = relPath.split(sep);
+  const name = basename(relPath, '.md');
+  if (parts[0] === 'domains' && parts[2] === 'compiled') {
+    // typeDir is the FULL sub-path between compiled/ and the file, so a nested object
+    // (compiled/decisions/archive/x.md) fails the type↔path check instead of passing
+    // as a flat one — the path schema is flat compiled/{type-dir}/{name}.md.
+    const typeDir = parts.slice(3, -1).join('/');
+    return { layer: 'domain', domain: parts[1], typeDir, codexKind: null, name };
+  }
+  if (parts[0] === 'codex') {
+    if (relPath === join('codex', 'INDEX.md')) return null; // the codex map, not an object
+    const kind = parts[1] === 'seed' || parts[1] === 'personal' ? parts[1] : null;
+    return { layer: 'codex', domain: null, typeDir: null, codexKind: kind, name };
+  }
+  return null;
+}
+
+// The install's typed-object file set: domains/*/compiled/ objects + every codex file.
+// (The codex/INDEX.md map is filtered out downstream by contextFor returning null.)
+export async function listObjectFiles(installRoot) {
+  return [
+    ...(await walkMarkdown(installRoot, join(installRoot, 'domains'))).filter(
+      (p) => p.split(sep)[2] === 'compiled',
+    ),
+    ...(await walkMarkdown(installRoot, join(installRoot, 'codex'))),
+  ];
+}
+
+// The RETRIEVAL-facing object set: every typed object EXCEPT the shipped seed library.
+// codex/seed/ is quarantined OUT of retrieval (specs/compile-retrieve-loop.md
+// §"Seed-vs-personal quarantine") — seed objects never enter the link/search index, so a
+// seed can never surface in recall/query even if a downstream scope filter regresses, and
+// a fresh install's index stays empty until the operator compiles their own work. Seed
+// discoverability stays with codex/INDEX.md + lint. `validate` and `lint` deliberately keep
+// scanning the FULL listObjectFiles set — seeds ARE contract-checked and lint-surfaced
+// (never-adopted drop suggestions); only the retrieval indices use this filtered view.
+export async function listRetrievableObjectFiles(installRoot) {
+  return (await listObjectFiles(installRoot)).filter((rel) => contextFor(rel)?.codexKind !== 'seed');
+}