@owlmeans/viable-common 0.0.44 → 0.0.45

package/src/integrity/utils.ts

@@ -1,320 +1,21 @@
-import { HARNESS_PROTECTED, ROOT_PROTECTED } from './consts.local.js'
-import { TARGET_BUNDLED_PACKAGES, TARGET_CURRENT_LAYOUT, TARGET_LEGACY_BUNDLED_PACKAGES, TARGET_LEGACY_PACKAGES, TARGET_LEGACY_PACKAGES_DIR, TARGET_PACKAGES_DIR, TargetLayout, TargetLegacyPackage, TargetPackage } from './consts.js'
+import type { TargetLayout } from './consts.js'
+import { targetLayoutHelper } from './layout.js'
 import type { TargetLayoutManifest } from './types.js'
 
-const fileIn = (dir: string, pkg: string, path: string): string => `${dir}/${pkg}/${path}`
+/** @deprecated compat:factory-refactor — use `targetLayoutHelper.targetManifest(…)` */
+export const targetManifest = (layout: TargetLayout): TargetLayoutManifest => targetLayoutHelper.targetManifest(layout)
 
-const protectedOf = (
-  dir: string, packages: readonly string[], bundled: readonly string[]
-): readonly string[] => [
-  ...ROOT_PROTECTED,
-  ...HARNESS_PROTECTED,
-  ...packages.flatMap(pkg => [fileIn(dir, pkg, 'package.json'), fileIn(dir, pkg, 'tsconfig.json')]),
-  ...bundled.flatMap(pkg =>
-    [fileIn(dir, pkg, 'rollup.config.js'), fileIn(dir, pkg, 'rollup.build.mjs')]),
-]
-
-const v2 = (pkg: TargetPackage, path: string): string =>
-  fileIn(TARGET_PACKAGES_DIR, pkg, path)
-
-const v1 = (pkg: TargetLegacyPackage, path: string): string =>
-  fileIn(TARGET_LEGACY_PACKAGES_DIR, pkg, path)
-
-/**
- * The current layout: five workspace packages under `sources/`.
- *
- * `common` and `backend` are libraries the other three import, so they emit declarations with
- * `tsc -b` rather than a bundle; `api`, `web` and `worker` each bundle themselves.
- */
-const V2_MANIFEST: TargetLayoutManifest = {
-  layout: TargetLayout.V2,
-  dir: TARGET_PACKAGES_DIR,
-  packages: Object.values(TargetPackage),
-  // The same file the publisher's own filesystem detection probes for (`sources/api`), so the
-  // two answers about one volume cannot disagree.
-  probe: v2(TargetPackage.Api, 'package.json'),
-  files: [
-    'package.json',
-    'bunfig.toml',
-    v2(TargetPackage.Common, 'package.json'),
-    v2(TargetPackage.Common, 'tsconfig.json'),
-    v2(TargetPackage.Common, 'src/index.ts'),
-    v2(TargetPackage.Common, 'src/entrypoints.ts'),
-    v2(TargetPackage.Backend, 'package.json'),
-    v2(TargetPackage.Backend, 'tsconfig.json'),
-    v2(TargetPackage.Backend, 'src/index.ts'),
-    v2(TargetPackage.Backend, 'src/context.ts'),
-    v2(TargetPackage.Backend, 'src/config.ts'),
-    v2(TargetPackage.Api, 'package.json'),
-    v2(TargetPackage.Api, 'tsconfig.json'),
-    v2(TargetPackage.Api, 'rollup.config.js'),
-    v2(TargetPackage.Api, 'rollup.build.mjs'),
-    v2(TargetPackage.Api, 'src/index.ts'),
-    v2(TargetPackage.Api, 'src/owlmeans.ts'),
-    v2(TargetPackage.Api, 'src/config.ts'),
-    v2(TargetPackage.Api, 'src/entrypoints.ts'),
-    v2(TargetPackage.Web, 'package.json'),
-    v2(TargetPackage.Web, 'tsconfig.json'),
-    v2(TargetPackage.Web, 'rollup.config.js'),
-    v2(TargetPackage.Web, 'rollup.build.mjs'),
-    v2(TargetPackage.Web, 'src/index.tsx'),
-    v2(TargetPackage.Web, 'src/owlmeans.ts'),
-    v2(TargetPackage.Web, 'src/config.ts'),
-    v2(TargetPackage.Web, 'src/entrypoints.ts'),
-    v2(TargetPackage.Worker, 'package.json'),
-    v2(TargetPackage.Worker, 'tsconfig.json'),
-    v2(TargetPackage.Worker, 'rollup.config.js'),
-    v2(TargetPackage.Worker, 'rollup.build.mjs'),
-    v2(TargetPackage.Worker, 'src/index.ts'),
-    v2(TargetPackage.Worker, 'src/owlmeans.ts'),
-    v2(TargetPackage.Worker, 'src/config.ts'),
-    v2(TargetPackage.Worker, 'src/entrypoints.ts'),
-  ],
-  protectedFiles: protectedOf(
-    TARGET_PACKAGES_DIR, Object.values(TargetPackage), TARGET_BUNDLED_PACKAGES),
-  buildScripts: {
-    [TargetPackage.Common]: 'tsc -b',
-    [TargetPackage.Backend]: 'tsc -b',
-    [TargetPackage.Api]: 'bun ./rollup.build.mjs',
-    [TargetPackage.Web]: 'bun ./rollup.build.mjs',
-    [TargetPackage.Worker]: 'bun ./rollup.build.mjs',
-  },
-  requiredDeps: {
-    [TargetPackage.Common]: ['@owlmeans/context', '@owlmeans/entrypoint'],
-    [TargetPackage.Backend]: ['@owlmeans/context', '@owlmeans/postgres-resource'],
-    [TargetPackage.Api]: ['@owlmeans/server-app'],
-    [TargetPackage.Web]: ['@owlmeans/web-client'],
-    [TargetPackage.Worker]: ['@owlmeans/queue', '@owlmeans/redis-queue'],
-  },
-  // `api` and `worker` both reach the database through `backend`, which is the whole reason
-  // `backend` is a library: two runtimes, one context factory, one set of resources. A `worker`
-  // that stopped depending on `backend` is processing jobs against something else.
-  workspaceDeps: {
-    [TargetPackage.Common]: [],
-    [TargetPackage.Backend]: [TargetPackage.Common],
-    [TargetPackage.Api]: [TargetPackage.Common, TargetPackage.Backend],
-    [TargetPackage.Web]: [TargetPackage.Common],
-    [TargetPackage.Worker]: [TargetPackage.Backend],
-  },
-  workspaceGlob: `${TARGET_PACKAGES_DIR}/*`,
-  workspaceEntries: Object.values(TargetPackage).map(pkg => `${TARGET_PACKAGES_DIR}/${pkg}`),
-  markers: {
-    [v2(TargetPackage.Common, 'src/index.ts')]: ['./entrypoints.js'],
-    [v2(TargetPackage.Backend, 'src/index.ts')]: ['./context.js'],
-    [v2(TargetPackage.Backend, 'src/context.ts')]: ['@owlmeans/context', 'makeContext'],
-    [v2(TargetPackage.Api, 'src/index.ts')]: ['./owlmeans.js', 'initOwlMeans'],
-    [v2(TargetPackage.Api, 'src/owlmeans.ts')]: ['@owlmeans/server-app', 'makeContext'],
-    [v2(TargetPackage.Web, 'src/index.tsx')]: ['@owlmeans/web-client', 'renderApp', './owlmeans'],
-    [v2(TargetPackage.Web, 'src/owlmeans.ts')]: ['makeContext', 'owlCtx'],
-    // The worker binds nothing but its health port; what makes it a worker is that it listens.
-    [v2(TargetPackage.Worker, 'src/index.ts')]: ['./owlmeans.js', 'initOwlMeans'],
-    [v2(TargetPackage.Worker, 'src/owlmeans.ts')]: ['@owlmeans/queue', 'makeContext'],
-    // The build configuration itself: what it reads and what it emits. These are the paths the
-    // publisher spawns and serves, so a config that redirects either one is a different program.
-    // Matched loosely enough to survive the `path.resolve(srcDir, …)` the template writes them
-    // with, and strictly enough that an input or an output somewhere else fails.
-    [v2(TargetPackage.Api, 'rollup.config.js')]: ['input:', 'index.ts', 'dist', 'index.js'],
-    [v2(TargetPackage.Web, 'rollup.config.js')]: ['input:', 'index.tsx', 'dist', 'bundle.js'],
-    [v2(TargetPackage.Worker, 'rollup.config.js')]: ['input:', 'index.ts', 'dist', 'index.js'],
-  },
-}
-
-/**
- * The legacy layout: three workspace packages under `packages/`.
- *
- * Frozen — nothing generates one any more, and every rule here is stated against the trees that
- * exist rather than against a template this repository still ships (it does not). `backend` is
- * the HTTP server AND the data layer, which is why it carries both `@owlmeans/server-app` and
- * `@owlmeans/postgres-resource`; `common` is the only library.
- */
-const V1_MANIFEST: TargetLayoutManifest = {
-  layout: TargetLayout.V1,
-  dir: TARGET_LEGACY_PACKAGES_DIR,
-  packages: TARGET_LEGACY_PACKAGES,
-  // `packages/backend` again — the publisher's own marker for this layout.
-  probe: v1(TargetLegacyPackage.Backend, 'package.json'),
-  files: [
-    'package.json',
-    'bunfig.toml',
-    v1(TargetLegacyPackage.Common, 'package.json'),
-    v1(TargetLegacyPackage.Common, 'tsconfig.json'),
-    v1(TargetLegacyPackage.Common, 'src/index.ts'),
-    v1(TargetLegacyPackage.Common, 'src/entrypoints.ts'),
-    v1(TargetLegacyPackage.Backend, 'package.json'),
-    v1(TargetLegacyPackage.Backend, 'tsconfig.json'),
-    v1(TargetLegacyPackage.Backend, 'rollup.config.js'),
-    v1(TargetLegacyPackage.Backend, 'rollup.build.mjs'),
-    v1(TargetLegacyPackage.Backend, 'src/index.ts'),
-    v1(TargetLegacyPackage.Backend, 'src/owlmeans.ts'),
-    v1(TargetLegacyPackage.Backend, 'src/config.ts'),
-    v1(TargetLegacyPackage.Backend, 'src/entrypoints.ts'),
-    v1(TargetLegacyPackage.Frontend, 'package.json'),
-    v1(TargetLegacyPackage.Frontend, 'tsconfig.json'),
-    v1(TargetLegacyPackage.Frontend, 'rollup.config.js'),
-    v1(TargetLegacyPackage.Frontend, 'rollup.build.mjs'),
-    v1(TargetLegacyPackage.Frontend, 'src/index.tsx'),
-    v1(TargetLegacyPackage.Frontend, 'src/owlmeans.ts'),
-    v1(TargetLegacyPackage.Frontend, 'src/config.ts'),
-    v1(TargetLegacyPackage.Frontend, 'src/entrypoints.ts'),
-  ],
-  protectedFiles: protectedOf(
-    TARGET_LEGACY_PACKAGES_DIR, TARGET_LEGACY_PACKAGES, TARGET_LEGACY_BUNDLED_PACKAGES),
-  buildScripts: {
-    [TargetLegacyPackage.Common]: 'tsc -b',
-    [TargetLegacyPackage.Backend]: 'bun ./rollup.build.mjs',
-    [TargetLegacyPackage.Frontend]: 'bun ./rollup.build.mjs',
-  },
-  requiredDeps: {
-    [TargetLegacyPackage.Common]: ['@owlmeans/context', '@owlmeans/entrypoint'],
-    [TargetLegacyPackage.Backend]: ['@owlmeans/server-app', '@owlmeans/postgres-resource'],
-    [TargetLegacyPackage.Frontend]: ['@owlmeans/web-client'],
-  },
-  workspaceDeps: {
-    [TargetLegacyPackage.Common]: [],
-    [TargetLegacyPackage.Backend]: [TargetLegacyPackage.Common],
-    [TargetLegacyPackage.Frontend]: [TargetLegacyPackage.Common],
-  },
-  workspaceGlob: `${TARGET_LEGACY_PACKAGES_DIR}/*`,
-  workspaceEntries: TARGET_LEGACY_PACKAGES.map(pkg => `${TARGET_LEGACY_PACKAGES_DIR}/${pkg}`),
-  markers: {
-    [v1(TargetLegacyPackage.Common, 'src/index.ts')]: ['./entrypoints.js'],
-    [v1(TargetLegacyPackage.Backend, 'src/index.ts')]: ['./owlmeans.js', 'initOwlMeans'],
-    [v1(TargetLegacyPackage.Backend, 'src/owlmeans.ts')]: ['@owlmeans/server-app', 'makeContext'],
-    [v1(TargetLegacyPackage.Frontend, 'src/index.tsx')]:
-      ['@owlmeans/web-client', 'renderApp', './owlmeans'],
-    [v1(TargetLegacyPackage.Frontend, 'src/owlmeans.ts')]: ['makeContext', 'owlCtx'],
-    [v1(TargetLegacyPackage.Backend, 'rollup.config.js')]:
-      ['input:', 'index.ts', 'dist', 'index.js'],
-    [v1(TargetLegacyPackage.Frontend, 'rollup.config.js')]:
-      ['input:', 'index.tsx', 'dist', 'bundle.js'],
-  },
-}
-
-/**
- * Every layout the platform is willing to run, keyed by its own name.
- *
- * Declared current-first, and the order is load-bearing: detection walks it and takes the first
- * probe it finds, so a half-migrated tree carrying both is verified against the layout the
- * platform generates today rather than against the frozen one.
- */
-export const TARGET_LAYOUTS: Readonly<Record<TargetLayout, TargetLayoutManifest>> = {
-  [TargetLayout.V2]: V2_MANIFEST,
-  [TargetLayout.V1]: V1_MANIFEST,
-}
-
-/** What one layout asserts. */
-export const targetManifest = (layout: TargetLayout): TargetLayoutManifest =>
-  TARGET_LAYOUTS[layout]
-
-/**
- * Whether a tree of this layout can still be GENERATED INTO.
- *
- * A legacy target is served, built and run exactly like any other — that is the whole point of
- * verifying it against its own manifest. What no longer works on it is code generation: every
- * path builder, every stamped import specifier and the whole `docs/` metadata tree name the
- * current layout's packages, so a story implemented into a legacy tree writes files into
- * directories its workspace does not contain. That fails silently — the build succeeds, the
- * story completes and the application does not change — which is why the platform refuses
- * instead, and names re-initialization as the one cure.
- *
- * `undefined` reads as current: a publisher that predates layout reporting omits it, and reading
- * that silence as legacy would refuse development for every slot already in the cluster.
- */
+/** @deprecated compat:factory-refactor — use `targetLayoutHelper.isLegacyLayout(…)` */
 export const isLegacyLayout = (layout: TargetLayout | string | undefined | null): boolean =>
-  layout != null && layout !== TARGET_CURRENT_LAYOUT
-
-/**
- * The files whose presence tells the layouts apart.
- *
- * Each layout's probe is a path the other cannot have. They are members of their own layout's
- * file list too, so a caller that reads {@link TARGET_INTEGRITY_FILES} always has both in hand —
- * which is the whole reason detection works at all. It did not before: the probe for the legacy
- * layout was declared but never read, so `detectTargetLayout` could only ever answer `V2`.
- */
-export const TARGET_LAYOUT_PROBE_FILES: readonly string[] =
-  Object.values(TARGET_LAYOUTS).map(manifest => manifest.probe)
-
-/**
- * Which layout a tree is in, from its files alone — IO-free, like everything else here.
- *
- * A tree that shows neither probe is reported as the current layout: it is not a target at all,
- * and the integrity report is what has to say so, in the vocabulary of the layout the platform
- * generates today.
- */
-export const detectTargetLayout = (files: Record<string, string | null>): TargetLayout => {
-  for (const manifest of Object.values(TARGET_LAYOUTS)) {
-    if (files[manifest.probe] != null) {
-      return manifest.layout
-    }
-  }
-
-  return TARGET_CURRENT_LAYOUT
-}
-
-/**
- * Files a caller must read and hand to `verifyTargetShape`.
- *
- * The UNION over every layout, because a caller reads before it knows which layout it is holding
- * and the probes are what settle that. The verifier reports only the files its selected layout
- * actually requires, so the extra reads cost a `stat` each and never a violation.
- *
- * The verifier is pure and does no IO of its own — the publisher reads these from the PVC, and
- * a test reads them from the template tree. A path that does not exist is passed as `null`,
- * which the verifier reports rather than skipping: absence is a violation for everything here.
- */
-export const TARGET_INTEGRITY_FILES: readonly string[] = [
-  ...new Set(Object.values(TARGET_LAYOUTS).flatMap(manifest => manifest.files)),
-]
-
-/**
- * Files no user-facing write may touch, through any path — the union over every layout.
- *
- * These are the ones that decide what gets EXECUTED — the build scripts, the package manifests
- * that name them, the compiler configuration that resolves them, and the install configuration.
- * The agent harness is here for the same reason: `.claude/settings.json` declares a
- * `SessionStart` hook and `.agents/scripts/link-skills.sh` is the command it spawns, so a write
- * to either runs code in the slot the next time an agent session opens, with no build and no
- * request involved. The agent's own generator already refuses the wiring sources
- * (`WIRING_SOURCES`), but that guard is LLM-scoped: it never saw a manual editor save and never
- * saw a git merge.
- *
- * The union rather than the current layout's list, because this is a path-shaped refusal with
- * nothing to gain from being narrow: a v2 path cannot exist in a v1 tree, so covering both costs
- * nothing and covers the legacy slots that were left writable.
- */
-export const TARGET_PROTECTED_FILES: readonly string[] = [
-  ...new Set(Object.values(TARGET_LAYOUTS).flatMap(manifest => manifest.protectedFiles)),
-]
-
-/** `<slug>-<package>` — the only way a workspace package is ever named, in either layout. */
-export const targetPackageName = (slug: string, pkg: string): string => `${slug}-${pkg}`
-
-/** Everything one package must declare, once the root manifest has named the slug. */
-export const targetRequiredDeps = (
-  slug: string, pkg: string, layout: TargetLayout = TARGET_CURRENT_LAYOUT
-): string[] => {
-  const manifest = targetManifest(layout)
-
-  return [
-    ...(manifest.requiredDeps[pkg] ?? []),
-    ...(manifest.workspaceDeps[pkg] ?? []).map(dep => targetPackageName(slug, dep)),
-  ]
-}
-
-/**
- * The current layout's own rules, kept as named constants because consumers outside the verifier
- * ask about the tree the platform generates today — never about a frozen one.
- */
-export const TARGET_BUILD_SCRIPTS: Readonly<Record<string, string>> = V2_MANIFEST.buildScripts
-
-export const TARGET_REQUIRED_DEPS: Readonly<Record<string, readonly string[]>> =
-  V2_MANIFEST.requiredDeps
-
-export const TARGET_WORKSPACE_DEPS: Readonly<Record<string, readonly string[]>> =
-  V2_MANIFEST.workspaceDeps
+  targetLayoutHelper.isLegacyLayout(layout)
 
-export const TARGET_ENTRY_MARKERS: Readonly<Record<string, readonly string[]>> = V2_MANIFEST.markers
+/** @deprecated compat:factory-refactor — use `targetLayoutHelper.detectTargetLayout(…)` */
+export const detectTargetLayout = (files: Record<string, string | null>): TargetLayout =>
+  targetLayoutHelper.detectTargetLayout(files)
 
-export const TARGET_WORKSPACE_GLOB = V2_MANIFEST.workspaceGlob
+/** @deprecated compat:factory-refactor — use `targetLayoutHelper.targetPackageName(…)` */
+export const targetPackageName = (slug: string, pkg: string): string => targetLayoutHelper.targetPackageName(slug, pkg)
 
-export const TARGET_WORKSPACE_ENTRIES: readonly string[] = V2_MANIFEST.workspaceEntries
+/** @deprecated compat:factory-refactor — use `targetLayoutHelper.targetRequiredDeps(…)` */
+export const targetRequiredDeps = (slug: string, pkg: string, layout?: TargetLayout): string[] =>
+  targetLayoutHelper.targetRequiredDeps(slug, pkg, layout)

package/src/integrity/verify/types.ts

@@ -0,0 +1,26 @@
+import type { TargetFileMap, TargetIntegrityReport } from '../types.js'
+
+/** The integrity verdict on a target tree, and its one-line-per-violation rendering. */
+export interface TargetIntegrityHelper {
+  /**
+   * Decide whether a tree is the generated application, from its files alone.
+   *
+   * Pure and IO-free on purpose. The publisher reads the sandbox and calls this; a test reads
+   * the template and calls this; both then agree by construction. It is also why the check is
+   * cheap enough to sit in front of every spawn rather than only at the moments someone
+   * remembered to guard.
+   *
+   * The tree picks the manifest it is verified against. A slot holds the layout it was
+   * initialized with for the life of the project and nothing migrates it, so asserting the
+   * current layout unconditionally does not make the check stricter — it aims it at a tree that
+   * was never there, and every legacy slot answers with one `missing` violation per file it was
+   * never supposed to have. That refuses the application the platform itself generated.
+   *
+   * Every rule collects rather than short-circuits: a tree that fails is usually a person's
+   * repository, and telling them one thing at a time turns a fix into a dozen round trips
+   * through a pull that reverts itself each time.
+   */
+  verifyTargetShape: (files: TargetFileMap) => TargetIntegrityReport
+  /** One line per violation — what goes into a log, `slot.lastError`, or a build diagnostic. */
+  formatIntegrityReport: (report: TargetIntegrityReport) => string
+}