@metaobjectsdev/cli 1.0.1 → 1.0.3

package/src/lib/migrate-scope.ts

@@ -10,7 +10,7 @@
 // or a refusal that drifted between them would be drift the user reads.
 
 import type { Collection } from "@metaobjectsdev/sdk";
-import type { SchemaProvenance } from "@metaobjectsdev/migrate-ts";
+import type { ObjectScopePredicate, SchemaProvenance } from "@metaobjectsdev/migrate-ts";
 
 /**
  * Say what a declared `migrate.scope` left out, for `migrate` and `verify --db`
@@ -32,6 +32,56 @@ export function outOfScopeNote(command: string, names: readonly string[]): strin
   );
 }
 
+/**
+ * Say what a DEPENDENCY owns, for `migrate` and `verify --db` alike (FR-023).
+ *
+ * A dependency's nodes are loaded so this project's own model can resolve against
+ * them, and are governed by nobody here. That is not the same sentence as
+ * `outOfScopeNote`'s: an excluded import is usually not the result of anything the
+ * author wrote — a project with no `migrate.scope` at all still excludes its imports —
+ * so reporting it as "outside migrate.scope" would name a key that does not exist.
+ * It also carries the opt-in, which is the whole remedy: name the package.
+ */
+export function dependencyNote(command: string, names: readonly string[]): string {
+  return (
+    `meta ${command} — ${names.length} object(s) from dependencies not governed here ` +
+    `(name the package in migrate.scope to own them): ${names.join(", ")}`
+  );
+}
+
+/**
+ * Every exclusion a run owes the reader, each object named exactly ONCE.
+ *
+ * `outOfScope` is the full suppression set and `fromDependencies` a subset of it, so
+ * reporting both as-is would print an imported table twice under two different
+ * explanations. The partition happens here, once, rather than in each command.
+ */
+export function exclusionNotes(
+  command: string,
+  outOfScope: readonly string[],
+  fromDependencies: readonly string[],
+): string[] {
+  const notes: string[] = [];
+  const imported = new Set(fromDependencies);
+  const declared = outOfScope.filter((name) => !imported.has(name));
+  if (declared.length > 0) notes.push(outOfScopeNote(command, declared));
+  if (fromDependencies.length > 0) notes.push(dependencyNote(command, fromDependencies));
+  return notes;
+}
+
+/**
+ * The import predicate a schema run threads into migrate-ts, or NOTHING.
+ *
+ * Nothing is the load-bearing half. A project with no dependencies must reach
+ * `scopeExpectedSchema` exactly as it always did — passing a predicate that happens to
+ * answer `false` for everything is not the same thing, because supplying one at all
+ * leaves the untouched same-object path and changes `declaredSchemas` from absent to
+ * derived. One helper so all five call sites make that decision identically.
+ */
+export function importedOption(collection: Collection): { imported?: ObjectScopePredicate } {
+  return collection.dependencies.length > 0 ? { imported: collection.imported } : {};
+}
+
 /** How many loaded FQNs to name in the refusal below — enough to show the shape
  *  an author's patterns have to match, short enough to stay readable. */
 const EXAMPLE_FQN_CAP = 3;
@@ -70,8 +120,13 @@ export function migrateScopeMismatch(
    */
   provenance: () => SchemaProvenance,
 ): string | undefined {
-  const { inMigrateScope, migrateScopePatterns } = collection;
-  if (inMigrateScope === undefined) return undefined;
+  // The DECLARED `migrate.scope` alone, never the composed `inMigrateScope` (FR-023).
+  // The composed predicate also excludes imports, so a consumer whose only
+  // table-declaring objects come from a dependency — and who declared no scope at all
+  // — would be refused here, citing patterns that do not exist. There is nothing wrong
+  // with that project: its imports are excluded by design and it governs no tables yet.
+  const { declaredMigrateScope, migrateScopePatterns } = collection;
+  if (declaredMigrateScope === undefined) return undefined;
 
   // The declaring FQNs of every table and view the UNSCOPED model contributes —
   // the same provenance `scopeExpectedSchema` decides scope on, so the refusal
@@ -87,7 +142,7 @@ export function migrateScopeMismatch(
   // nothing for a pattern to govern, scoped or not, and an empty schema has its
   // own (much louder) failure modes downstream.
   if (fqns.length === 0) return undefined;
-  if (fqns.some(inMigrateScope)) return undefined;
+  if (fqns.some(declaredMigrateScope)) return undefined;
 
   const patterns = JSON.stringify(migrateScopePatterns ?? []);
   const examples = fqns.slice(0, EXAMPLE_FQN_CAP).join(", ");

package/src/lib/overlay-lint.ts

@@ -0,0 +1,129 @@
+// server/typescript/packages/cli/src/lib/overlay-lint.ts
+//
+// `meta verify` — the overlay AUTHORING lint (FR-023 §11.1 item 4).
+//
+// The parser's own merge rule (parser-core.ts, "Default: no operator →
+// silently reuse existing or create new") means a top-level redeclaration of
+// an existing node works TODAY whether or not it carries `overlay: true` —
+// as long as the target still exists under the same (type, resolutionKey).
+// That is exactly the trap: a consumer who redeclares an imported node
+// without the flag gets today's silent merge for free, and gets a silent NEW
+// OBJECT the day the upstream node is renamed or removed — no error, just a
+// second, disconnected node under the same name. `overlay: true` turns that
+// into a loud `ERR_OVERLAY_NO_TARGET` instead.
+//
+// This lint does not change that parser behavior (nor could it — it reads
+// raw file content, never the parser's merge decisions). It tells the AUTHOR:
+// every top-level (type, resolutionKey) declared in two or more of the
+// collection's files where more than one declaration lacks the flag. Exactly
+// one unflagged declaration is the base and is fine; every additional
+// unflagged one is a finding.
+//
+// Advisory only, like its sibling in requirement-lint.ts: never fails
+// `meta verify`, never changes load behavior. Deliberately NO severity
+// constant to flip — see requirement-lint.ts's header for why that promise
+// would be false here too.
+
+import { declaredTopLevelKeys, type DeclaredTopLevelKey, type MetaDataSource } from "@metaobjectsdev/metadata";
+import type { Collection } from "@metaobjectsdev/sdk";
+import { relPosix } from "./rel-posix.js";
+import type { Diagnostic } from "./requirement-check.js";
+
+export const WARN_OVERLAY_IMPLICIT = "WARN_OVERLAY_IMPLICIT";
+
+/**
+ * Resolve one collection file path to the `MetaDataSource` `lintOverlays`
+ * reads it through. Injected so the lint never touches the filesystem
+ * directly: the production wiring in `verify.ts` backs this with
+ * `FileSource` (from `@metaobjectsdev/metadata/core`); a test can supply an
+ * in-memory source instead.
+ */
+export type ReadSource = (path: string) => MetaDataSource;
+
+function warn(code: string, message: string): Diagnostic {
+  return { severity: "warn", code, message };
+}
+
+/** One file's declaration of a given (type, resolutionKey). */
+interface Declaration {
+  readonly file: string;
+  readonly overlay: boolean;
+}
+
+/**
+ * Lint the collection's files for unflagged cross-file redeclarations.
+ *
+ * Reads every file in `collection.files` — dependency artifacts first, since
+ * `Collection.files` already orders them that way and they are the BASES a
+ * consumer's own declarations amend — and structurally scans each with
+ * {@link declaredTopLevelKeys} (never the loaded/merged model: the merged
+ * tree has already lost which FILE contributed which declaration).
+ *
+ * Groups by (type, resolutionKey) — mirroring the parser's own merge lookup,
+ * which matches on type AND resolutionKey (parser-core.ts) — and reports
+ * every unflagged declaration after the first one for a key with 2+
+ * declarations. The first unflagged declaration is the base.
+ *
+ * `file` in each finding's message is the collection-relative path
+ * (`relPosix`), or the dependency's `dep:<name>/<artifact>` id when the
+ * declaration came from an imported artifact.
+ *
+ * Unreadable or unparsable files are skipped — the loader itself reports
+ * those (as a load error / `meta verify`'s own failure path); duplicating
+ * that diagnosis here would just be a second, worse-informed version of the
+ * same message.
+ */
+export async function lintOverlays(
+  collection: Collection,
+  readSource: ReadSource,
+): Promise<Diagnostic[]> {
+  // type -> resolutionKey -> every declaration seen for it, in file order.
+  const byType = new Map<string, Map<string, Declaration[]>>();
+
+  for (const path of collection.files) {
+    let declared: ReadonlyArray<DeclaredTopLevelKey>;
+    try {
+      const source = readSource(path);
+      const content = await source.read();
+      declared = await declaredTopLevelKeys(content, source.format);
+    } catch {
+      continue;
+    }
+    const file = collection.fileIds.get(path) ?? relPosix(collection.configDir, path);
+    for (const decl of declared) {
+      let byKey = byType.get(decl.type);
+      if (byKey === undefined) {
+        byKey = new Map<string, Declaration[]>();
+        byType.set(decl.type, byKey);
+      }
+      const list = byKey.get(decl.key) ?? [];
+      list.push({ file, overlay: decl.overlay });
+      byKey.set(decl.key, list);
+    }
+  }
+
+  const diags: Diagnostic[] = [];
+  for (const byKey of byType.values()) {
+    for (const [fqn, declarations] of byKey) {
+      if (declarations.length < 2) continue;
+      let baseSeen = false;
+      for (const decl of declarations) {
+        if (decl.overlay) continue;
+        if (!baseSeen) {
+          // The first unflagged declaration is the base — nothing to report.
+          baseSeen = true;
+          continue;
+        }
+        diags.push(
+          warn(
+            WARN_OVERLAY_IMPLICIT,
+            `${fqn} is redeclared in ${decl.file} without overlay: true — add the flag ` +
+              `so a removed or renamed target fails loudly (ERR_OVERLAY_NO_TARGET) instead ` +
+              `of silently becoming a new object`,
+          ),
+        );
+      }
+    }
+  }
+  return diags;
+}

package/src/lib/requirement-check.ts

@@ -249,11 +249,25 @@ export function collectRequirements(root: MetaData): MetaRequirement[] {
 export interface RequirementScan {
   readonly addressed: readonly AddressedRequirement[];
   readonly claimedObjects: ReadonlySet<string>;
+  /** FR-023 — narrows which entities `coverableEntities` counts. Undefined
+   *  means "every non-abstract entity is coverable", exactly as before this
+   *  option existed: a project with no dependencies gets no change at all.
+   *  Threaded through so BOTH `coverableEntities` call sites (the gate and the
+   *  summary) inherit the same narrowing — see `coverableEntities`. */
+  readonly coverable?: (fqn: string) => boolean;
 }
 
-export function scanRequirements(root: MetaData): RequirementScan {
+export function scanRequirements(
+  root: MetaData,
+  opts?: { coverable?: (fqn: string) => boolean },
+): RequirementScan {
   const addressed = collectAddressedRequirements(root);
-  return { addressed, claimedObjects: claimedObjectKeys(root, addressed.map((r) => r.node)) };
+  return {
+    addressed,
+    claimedObjects: claimedObjectKeys(root, addressed.map((r) => r.node)),
+    // `exactOptionalPropertyTypes` — an omitted key, never an explicit `undefined`.
+    ...(opts?.coverable !== undefined ? { coverable: opts.coverable } : {}),
+  };
 }
 
 /**
@@ -307,10 +321,22 @@ function claimedObjectKeys(root: MetaData, reqs: MetaRequirement[]): Set<string>
  * An ABSTRACT entity is shape, not data: there is no table and no rows, so
  * demanding a capability claim for it is the same category error as demanding
  * one for an object.value. It is exempt for the same reason.
+ *
+ * FR-023: an entity loaded from a dependency's synced snapshot is load-only —
+ * the publisher owns it, and this project never declared it — unless the
+ * project's own `scope.include` names the dependency's package literally
+ * (`Collection.inScope`, threaded in as `coverable`). Demanding a capability
+ * claim for an import nobody here opted into owning would report a project as
+ * failing to claim entities it does not own. `coverable` is applied INSIDE
+ * this function, once, so every call site inherits it — the alternative
+ * (filtering at a call site) is exactly the shape of bug this task exists to
+ * avoid: the other call site would keep counting imports.
  */
-function coverableEntities(root: MetaData): MetaData[] {
+function coverableEntities(root: MetaData, coverable?: (fqn: string) => boolean): MetaData[] {
   return root.children().filter(
-    (n) => n.type === TYPE_OBJECT && n.subType === OBJECT_SUBTYPE_ENTITY && !n.isAbstract,
+    (n) =>
+      n.type === TYPE_OBJECT && n.subType === OBJECT_SUBTYPE_ENTITY && !n.isAbstract &&
+      (coverable === undefined || coverable(n.resolutionKey())),
   );
 }
 
@@ -324,7 +350,7 @@ function coverableEntities(root: MetaData): MetaData[] {
  */
 export function checkRequirements(root: MetaData, scan: RequirementScan = scanRequirements(root)): Diagnostic[] {
   const out: Diagnostic[] = [];
-  const { addressed, claimedObjects } = scan;
+  const { addressed, claimedObjects, coverable } = scan;
   if (addressed.length === 0) return out; // opt-in by declaration — no requirements, nothing to say
 
   for (const { node: req, path: reqPath } of addressed) {
@@ -538,7 +564,7 @@ export function checkRequirements(root: MetaData, scan: RequirementScan = scanRe
   //
   // So a green run means "every entity is claimed by something", not "every node is
   // described". The stronger reading would be false.
-  for (const ent of coverableEntities(root)) {
+  for (const ent of coverableEntities(root, coverable)) {
     const key = ent.resolutionKey();
     if (!claimedObjects.has(key)) {
       out.push({
@@ -596,7 +622,7 @@ export function summariseRequirements(
   // summary cannot disagree with the diagnostics printed beneath it — previously
   // the same helper, now literally the same result.
   const claimed = scan.claimedObjects;
-  for (const ent of coverableEntities(root)) {
+  for (const ent of coverableEntities(root, scan.coverable)) {
     summary.entitiesTotal++;
     if (claimed.has(ent.resolutionKey())) summary.entitiesClaimed++;
   }