@vibe-agent-toolkit/cli 0.2.0-rc.10 → 0.2.0-rc.12

package/dist/commands/resources/scan-schema.d.ts

@@ -0,0 +1,195 @@
+/**
+ * The document `vat resources scan` publishes, apart from the command.
+ *
+ * A sibling module because the published-shape registry imports it and the
+ * command imports the writer that imports the registry: a schema declared in
+ * the command module itself would be an import cycle, read before it is
+ * initialised.
+ *
+ * 🔑 **The lab reads this document.** `packages/lab`'s population facet takes
+ * the file count from the envelope's `examined` and the population from
+ * `data.files` (with `--verbose`), qualified by `data.lane` and
+ * `data.extentSource`. A rename here is a rename there.
+ */
+import { type Report } from '@vibe-agent-toolkit/schema';
+import { z } from 'zod';
+import type { ExaminedDeclaration } from '../../utils/run-integrity.js';
+/** What `examined` counts for `vat resources scan`, and the remedy when it is zero. */
+export declare const RESOURCES_SCAN_EXAMINED: ExaminedDeclaration;
+declare const ResourcesScanDataSchema: z.ZodObject<{
+    /** The project root — the ONE base every `files[].path` is relative to. */
+    root: z.ZodString;
+    /** Which enumerator produced the population: the walk, or the projection lane. */
+    lane: z.ZodEnum<["walk" | "projection", ...("walk" | "projection")[]]>;
+    /**
+     * Which enumerator the projection lane used, or `null` for the walk. Always
+     * present: a key that vanished for the walk would read as a build too old to
+     * report one.
+     */
+    extentSource: z.ZodNullable<z.ZodEnum<[import("@vibe-agent-toolkit/resources").CrawlSourceKind, ...import("@vibe-agent-toolkit/resources").CrawlSourceKind[]]>>;
+    /** Resources per collection that has any (only the `--collection` one when filtered); `{}` when none. */
+    collections: z.ZodRecord<z.ZodString, z.ZodObject<{
+        resourceCount: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        resourceCount: number;
+    }, {
+        resourceCount: number;
+    }>>;
+    /** Present only under `--verbose`: every scanned file. */
+    files: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        /** Relative to `data.root`, forward slashes. */
+        path: z.ZodString;
+        /** Links the file carries. */
+        links: z.ZodNumber;
+        /** Headings the file carries, every nested level counted. */
+        anchors: z.ZodNumber;
+        /** The content checksum the registry keyed the file on. */
+        checksum: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        path: string;
+        links: number;
+        anchors: number;
+        checksum: string;
+    }, {
+        path: string;
+        links: number;
+        anchors: number;
+        checksum: string;
+    }>, "many">>;
+}, "strict", z.ZodTypeAny, {
+    root: string;
+    lane: "walk" | "projection";
+    extentSource: import("@vibe-agent-toolkit/resources").CrawlSourceKind | null;
+    collections: Record<string, {
+        resourceCount: number;
+    }>;
+    files?: {
+        path: string;
+        links: number;
+        anchors: number;
+        checksum: string;
+    }[] | undefined;
+}, {
+    root: string;
+    lane: "walk" | "projection";
+    extentSource: import("@vibe-agent-toolkit/resources").CrawlSourceKind | null;
+    collections: Record<string, {
+        resourceCount: number;
+    }>;
+    files?: {
+        path: string;
+        links: number;
+        anchors: number;
+        checksum: string;
+    }[] | undefined;
+}>;
+export type ResourcesScanData = z.infer<typeof ResourcesScanDataSchema>;
+/** The document this command publishes. */
+export declare const RESOURCES_SCAN_REPORT_SCHEMA: import("@vibe-agent-toolkit/schema").ReportZodSchema<z.ZodObject<{
+    /** The project root — the ONE base every `files[].path` is relative to. */
+    root: z.ZodString;
+    /** Which enumerator produced the population: the walk, or the projection lane. */
+    lane: z.ZodEnum<["walk" | "projection", ...("walk" | "projection")[]]>;
+    /**
+     * Which enumerator the projection lane used, or `null` for the walk. Always
+     * present: a key that vanished for the walk would read as a build too old to
+     * report one.
+     */
+    extentSource: z.ZodNullable<z.ZodEnum<[import("@vibe-agent-toolkit/resources").CrawlSourceKind, ...import("@vibe-agent-toolkit/resources").CrawlSourceKind[]]>>;
+    /** Resources per collection that has any (only the `--collection` one when filtered); `{}` when none. */
+    collections: z.ZodRecord<z.ZodString, z.ZodObject<{
+        resourceCount: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        resourceCount: number;
+    }, {
+        resourceCount: number;
+    }>>;
+    /** Present only under `--verbose`: every scanned file. */
+    files: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        /** Relative to `data.root`, forward slashes. */
+        path: z.ZodString;
+        /** Links the file carries. */
+        links: z.ZodNumber;
+        /** Headings the file carries, every nested level counted. */
+        anchors: z.ZodNumber;
+        /** The content checksum the registry keyed the file on. */
+        checksum: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        path: string;
+        links: number;
+        anchors: number;
+        checksum: string;
+    }, {
+        path: string;
+        links: number;
+        anchors: number;
+        checksum: string;
+    }>, "many">>;
+}, "strict", z.ZodTypeAny, {
+    root: string;
+    lane: "walk" | "projection";
+    extentSource: import("@vibe-agent-toolkit/resources").CrawlSourceKind | null;
+    collections: Record<string, {
+        resourceCount: number;
+    }>;
+    files?: {
+        path: string;
+        links: number;
+        anchors: number;
+        checksum: string;
+    }[] | undefined;
+}, {
+    root: string;
+    lane: "walk" | "projection";
+    extentSource: import("@vibe-agent-toolkit/resources").CrawlSourceKind | null;
+    collections: Record<string, {
+        resourceCount: number;
+    }>;
+    files?: {
+        path: string;
+        links: number;
+        anchors: number;
+        checksum: string;
+    }[] | undefined;
+}>, z.ZodObject<Omit<{
+    code: z.ZodString;
+    severity: z.ZodEnum<["error", "warning", "info", "ignore"]>;
+    message: z.ZodString;
+    location: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>;
+    line: z.ZodOptional<z.ZodNumber>;
+    field: z.ZodOptional<z.ZodString>;
+    link: z.ZodOptional<z.ZodString>;
+    fix: z.ZodOptional<z.ZodString>;
+    reference: z.ZodOptional<z.ZodString>;
+    suggestion: z.ZodOptional<z.ZodString>;
+}, "severity"> & {
+    severity: z.ZodEnum<["error", "warning", "info"]>;
+    column: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    code: string;
+    message: string;
+    severity: "error" | "warning" | "info";
+    fix?: string | undefined;
+    reference?: string | undefined;
+    location?: string | undefined;
+    line?: number | undefined;
+    field?: string | undefined;
+    link?: string | undefined;
+    suggestion?: string | undefined;
+    column?: number | undefined;
+}, {
+    code: string;
+    message: string;
+    severity: "error" | "warning" | "info";
+    fix?: string | undefined;
+    reference?: string | undefined;
+    location?: string | undefined;
+    line?: number | undefined;
+    field?: string | undefined;
+    link?: string | undefined;
+    suggestion?: string | undefined;
+    column?: number | undefined;
+}>>;
+export type ResourcesScanReport = Report<ResourcesScanData>;
+export {};
+//# sourceMappingURL=scan-schema.d.ts.map

package/dist/commands/resources/scan-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-schema.d.ts","sourceRoot":"","sources":["../../../src/commands/resources/scan-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAA+B,KAAK,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACtF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAExE,uFAAuF;AACvF,eAAO,MAAM,uBAAuB,EAAE,mBAKrC,CAAC;AAcF,QAAA,MAAM,uBAAuB;IAC3B,2EAA2E;;IAE3E,kFAAkF;;IAElF;;;;OAIG;;IAEH,yGAAyG;;;;;;;;IAEzG,0DAA0D;;QAvB1D,gDAAgD;;QAEhD,8BAA8B;;QAE9B,6DAA6D;;QAE7D,2DAA2D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmBlD,CAAC;AAEZ,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,2CAA2C;AAC3C,eAAO,MAAM,4BAA4B;IAnBvC,2EAA2E;;IAE3E,kFAAkF;;IAElF;;;;OAIG;;IAEH,yGAAyG;;;;;;;;IAEzG,0DAA0D;;QAvB1D,gDAAgD;;QAEhD,8BAA8B;;QAE9B,6DAA6D;;QAE7D,2DAA2D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwBmC,CAAC;AAEjG,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,iBAAiB,CAAC,CAAC"}

package/dist/commands/resources/scan-schema.js

@@ -0,0 +1,53 @@
+/**
+ * The document `vat resources scan` publishes, apart from the command.
+ *
+ * A sibling module because the published-shape registry imports it and the
+ * command imports the writer that imports the registry: a schema declared in
+ * the command module itself would be an import cycle, read before it is
+ * initialised.
+ *
+ * 🔑 **The lab reads this document.** `packages/lab`'s population facet takes
+ * the file count from the envelope's `examined` and the population from
+ * `data.files` (with `--verbose`), qualified by `data.lane` and
+ * `data.extentSource`. A rename here is a rename there.
+ */
+import { CRAWL_LANES, CRAWL_SOURCE_KINDS } from '@vibe-agent-toolkit/resources';
+import { FindingSchema, reportSchema } from '@vibe-agent-toolkit/schema';
+import { z } from 'zod';
+/** What `examined` counts for `vat resources scan`, and the remedy when it is zero. */
+export const RESOURCES_SCAN_EXAMINED = {
+    unit: 'files',
+    whenZero: 'The path names no markdown, resources.include/resources.exclude enumerate nothing (a broad exclude, a'
+        + ' shallow or sparse checkout, a root that resolved somewhere else), or --collection names a collection'
+        + ' no file matched.',
+};
+/** One scanned file, under `--verbose`. */
+const ScannedFileSchema = z.object({
+    /** Relative to `data.root`, forward slashes. */
+    path: z.string(),
+    /** Links the file carries. */
+    links: z.number().int().nonnegative(),
+    /** Headings the file carries, every nested level counted. */
+    anchors: z.number().int().nonnegative(),
+    /** The content checksum the registry keyed the file on. */
+    checksum: z.string(),
+}).strict();
+const ResourcesScanDataSchema = z.object({
+    /** The project root — the ONE base every `files[].path` is relative to. */
+    root: z.string(),
+    /** Which enumerator produced the population: the walk, or the projection lane. */
+    lane: z.enum(CRAWL_LANES),
+    /**
+     * Which enumerator the projection lane used, or `null` for the walk. Always
+     * present: a key that vanished for the walk would read as a build too old to
+     * report one.
+     */
+    extentSource: z.enum(CRAWL_SOURCE_KINDS).nullable(),
+    /** Resources per collection that has any (only the `--collection` one when filtered); `{}` when none. */
+    collections: z.record(z.string(), z.object({ resourceCount: z.number().int().nonnegative() }).strict()),
+    /** Present only under `--verbose`: every scanned file. */
+    files: z.array(ScannedFileSchema).optional(),
+}).strict();
+/** The document this command publishes. */
+export const RESOURCES_SCAN_REPORT_SCHEMA = reportSchema(ResourcesScanDataSchema, FindingSchema);
+//# sourceMappingURL=scan-schema.js.map

package/dist/commands/resources/scan-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-schema.js","sourceRoot":"","sources":["../../../src/commands/resources/scan-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAChF,OAAO,EAAE,aAAa,EAAE,YAAY,EAAe,MAAM,4BAA4B,CAAC;AACtF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,uFAAuF;AACvF,MAAM,CAAC,MAAM,uBAAuB,GAAwB;IAC1D,IAAI,EAAE,OAAO;IACb,QAAQ,EAAE,uGAAuG;UAC7G,uGAAuG;UACvG,mBAAmB;CACxB,CAAC;AAEF,2CAA2C;AAC3C,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACjC,gDAAgD;IAChD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,8BAA8B;IAC9B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IACrC,6DAA6D;IAC7D,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IACvC,2DAA2D;IAC3D,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;CACrB,CAAC,CAAC,MAAM,EAAE,CAAC;AAEZ,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,2EAA2E;IAC3E,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,kFAAkF;IAClF,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC;IACzB;;;;OAIG;IACH,YAAY,EAAE,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,QAAQ,EAAE;IACnD,yGAAyG;IACzG,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;IACvG,0DAA0D;IAC1D,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC,QAAQ,EAAE;CAC7C,CAAC,CAAC,MAAM,EAAE,CAAC;AAIZ,2CAA2C;AAC3C,MAAM,CAAC,MAAM,4BAA4B,GAAG,YAAY,CAAC,uBAAuB,EAAE,aAAa,CAAC,CAAC"}

package/dist/commands/resources/scan.d.ts

@@ -3,6 +3,7 @@
  */
 import type { CrawlSourceKind } from '@vibe-agent-toolkit/resources';
 import { type ResourceCrawlLane } from '../../utils/resource-loader.js';
+import type { ResourcesScanReport } from './scan-schema.js';
 interface ScanOptions {
     debug?: boolean;
     verbose?: boolean;
@@ -52,21 +53,43 @@ export interface ScanPayloadInput {
      */
     extentSource: CrawlSourceKind | null;
     durationMs: number;
+    /** Resources per collection; `{}` when the project configures none. */
     collections: Record<string, {
         resourceCount: number;
-    }> | undefined;
+    }>;
     verbose: boolean;
 }
 /**
- * Build the scan payload.
+ * Build the scan report.
  *
  * Pure: no file system, no clock, no `process.exit`. The registry keeps
  * absolute `filePath`s because that is the identity it keys on; re-basing onto
  * the stated root happens exactly once, here, at the document boundary — the
  * same contract `vat audit` follows. A payload of `$HOME`-absolute paths names
  * the machine it ran on and cannot be diffed across two checkouts.
+ *
+ * `examined` is the number of files scanned — the denominator the lab's
+ * population facet reads, beside `data.files`. A scan has no findings of its
+ * own; a scan of nothing gets the writer's run-integrity refusal.
+ */
+export declare function buildScanReport(input: ScanPayloadInput): ResourcesScanReport;
+/**
+ * Resources per collection, narrowed to the `--collection` one when filtering —
+ * the same rule `resources validate` follows: the registry's stats list only
+ * collections with members, so a declared collection that matched nothing is
+ * absent rather than listed at 0.
  */
-export declare function buildScanOutputData(input: ScanPayloadInput): Record<string, unknown>;
+declare function collectionCounts(collectionStats: {
+    collections: Record<string, {
+        resourceCount: number;
+    }>;
+} | undefined, collection: string | undefined): Record<string, {
+    resourceCount: number;
+}>;
+/** Test seam: the per-collection counts `--collection` narrows. */
+export declare const __internal: {
+    collectionCounts: typeof collectionCounts;
+};
 export declare function scanCommand(pathArg: string | undefined, options: ScanOptions): Promise<void>;
 export {};
 //# sourceMappingURL=scan.d.ts.map

package/dist/commands/resources/scan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../../../src/commands/resources/scan.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AASrE,OAAO,EAA2B,KAAK,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAEjG,UAAU,WAAW;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,kEAAkE;AAClE,KAAK,mBAAmB,GAAG;IAAE,QAAQ,CAAC,EAAE,mBAAmB,EAAE,GAAG,SAAS,CAAA;CAAE,CAAC;AAE5E;;;;;;GAMG;AACH,UAAU,YAAY;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,SAAS,OAAO,EAAE,CAAC;IAC1B,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,SAAS,YAAY,EAAE,CAAC;IACnC,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;OAQG;IACH,IAAI,EAAE,iBAAiB,CAAC;IACxB;;;;;;;;OAQG;IACH,YAAY,EAAE,eAAe,GAAG,IAAI,CAAC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,SAAS,CAAC;IACnE,OAAO,EAAE,OAAO,CAAC;CAClB;AAaD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA0BpF;AAED,wBAAsB,WAAW,CAC/B,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC,CAqDf"}
+{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../../../src/commands/resources/scan.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAQrE,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,gCAAgC,CAAC;AAExC,OAAO,KAAK,EAAqB,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAE/E,UAAU,WAAW;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,kEAAkE;AAClE,KAAK,mBAAmB,GAAG;IAAE,QAAQ,CAAC,EAAE,mBAAmB,EAAE,GAAG,SAAS,CAAA;CAAE,CAAC;AAE5E;;;;;;GAMG;AACH,UAAU,YAAY;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,SAAS,OAAO,EAAE,CAAC;IAC1B,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,SAAS,YAAY,EAAE,CAAC;IACnC,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;OAQG;IACH,IAAI,EAAE,iBAAiB,CAAC;IACxB;;;;;;;;OAQG;IACH,YAAY,EAAE,eAAe,GAAG,IAAI,CAAC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvD,OAAO,EAAE,OAAO,CAAC;CAClB;AAaD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,gBAAgB,GAAG,mBAAmB,CA2B5E;AAED;;;;;GAKG;AACH,iBAAS,gBAAgB,CACvB,eAAe,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,GAAG,SAAS,EACvF,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,MAAM,CAAC,MAAM,EAAE;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC,CAK3C;AAED,mEAAmE;AACnE,eAAO,MAAM,UAAU;;CAAuB,CAAC;AAE/C,wBAAsB,WAAW,CAC/B,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC,CAiCf"}

package/dist/commands/resources/scan.js

@@ -1,14 +1,13 @@
 /**
  * Resources scan command - discover markdown resources
  */
-import { ExitCode } from '@vibe-agent-toolkit/schema';
-import { handleCommandError } from '../../utils/command-error.js';
-import { formatDurationSecs } from '../../utils/duration.js';
+import { buildReport } from '@vibe-agent-toolkit/schema';
+import { refusalCodeOf } from '../../utils/command-refusal.js';
+import { endWithRefusal, endWithReport, NOTHING_FINISHED } from '../../utils/document-writer.js';
 import { createLogger } from '../../utils/logger.js';
-import { writeStructuredOutput } from '../../utils/output.js';
 import { projectRootOrLoudCwd } from '../../utils/project-root-policy.js';
 import { relativizePathEntries } from '../../utils/relativize-paths.js';
-import { loadResourcesWithConfig } from '../../utils/resource-loader.js';
+import { assertDeclaredCollection, extentSourceOf, loadResourcesWithConfig, } from '../../utils/resource-loader.js';
 /** Total headings in a tree, counting every nested level. */
 function countHeadings(headings) {
     let count = headings.length;
@@ -20,24 +19,21 @@ function countHeadings(headings) {
     return count;
 }
 /**
- * Build the scan payload.
+ * Build the scan report.
  *
  * Pure: no file system, no clock, no `process.exit`. The registry keeps
  * absolute `filePath`s because that is the identity it keys on; re-basing onto
  * the stated root happens exactly once, here, at the document boundary — the
  * same contract `vat audit` follows. A payload of `$HOME`-absolute paths names
  * the machine it ran on and cannot be diffed across two checkouts.
+ *
+ * `examined` is the number of files scanned — the denominator the lab's
+ * population facet reads, beside `data.files`. A scan has no findings of its
+ * own; a scan of nothing gets the writer's run-integrity refusal.
  */
-export function buildScanOutputData(input) {
+export function buildScanReport(input) {
     const { resources, root, lane, extentSource, durationMs, collections, verbose } = input;
-    const files = resources.map((resource) => ({
-        path: resource.filePath,
-        links: resource.links.length,
-        anchors: countHeadings(resource.headings),
-        checksum: resource.checksum,
-    }));
-    return {
-        status: 'success',
+    const data = {
         // Stated once, and the only absolute path in the document.
         root,
         lane,
@@ -45,60 +41,62 @@ export function buildScanOutputData(input) {
         // indistinguishable from a build too old to report it, which is the same
         // absence-vs-old-build ambiguity the two lane markers exist to avoid.
         extentSource,
-        filesScanned: resources.length,
-        linksFound: resources.reduce((sum, r) => sum + r.links.length, 0),
-        anchorsFound: files.reduce((sum, f) => sum + f.anchors, 0),
-        durationSecs: formatDurationSecs(durationMs),
-        ...(collections ? { collections } : {}),
-        ...(verbose ? { files: relativizePathEntries(files, root) } : {}),
+        collections,
     };
+    if (verbose) {
+        data.files = relativizePathEntries(resources.map((resource) => ({
+            path: resource.filePath,
+            links: resource.links.length,
+            anchors: countHeadings(resource.headings),
+            checksum: resource.checksum,
+        })), root);
+    }
+    // `vat resources scan` offers no `--strict`, and reports no finding of its own.
+    return buildReport({ examined: resources.length, findings: [], data, gate: { strict: false }, durationMs });
+}
+/**
+ * Resources per collection, narrowed to the `--collection` one when filtering —
+ * the same rule `resources validate` follows: the registry's stats list only
+ * collections with members, so a declared collection that matched nothing is
+ * absent rather than listed at 0.
+ */
+function collectionCounts(collectionStats, collection) {
+    const counts = Object.entries(collectionStats?.collections ?? {})
+        .filter(([id]) => collection === undefined || id === collection)
+        .map(([id, stat]) => [id, { resourceCount: stat.resourceCount }]);
+    return Object.fromEntries(counts);
 }
+/** Test seam: the per-collection counts `--collection` narrows. */
+export const __internal = { collectionCounts };
 export async function scanCommand(pathArg, options) {
     const logger = createLogger({ debug: options.debug ?? false });
     const startTime = Date.now();
+    // The two formats this verb offers (Commander refuses any other).
+    const format = options.format === 'json' ? 'json' : 'yaml';
     try {
         // Resolve projectRoot at the CLI boundary (spec §5/§7 — loud-cwd policy).
         const projectRoot = projectRootOrLoudCwd(pathArg ?? process.cwd(), logger);
         // Load resources with config support
-        const { registry, lane, extentSource } = await loadResourcesWithConfig(pathArg, projectRoot, logger);
+        const { registry, config, population } = await loadResourcesWithConfig(pathArg, projectRoot, logger);
+        assertDeclaredCollection(config, options.collection);
         // Get all resources (filtered by collection if specified)
-        let allResources = registry.getAllResources();
-        if (options.collection) {
-            const { collection } = options;
-            allResources = allResources.filter(r => {
-                return collection ? r.collections?.includes(collection) ?? false : false;
-            });
-        }
-        // Build collection stats (filtered or all)
-        let collectionsOutput;
-        if (options.collection) {
-            // When filtering by collection, only show that collection
-            collectionsOutput = { [options.collection]: { resourceCount: allResources.length } };
-        }
-        else {
-            // Show all collections
-            const collectionStats = registry.getCollectionStats();
-            collectionsOutput = collectionStats
-                ? Object.fromEntries(Object.entries(collectionStats.collections).map(([id, stat]) => [
-                    id,
-                    { resourceCount: stat.resourceCount },
-                ]))
-                : undefined;
-        }
-        const payload = buildScanOutputData({
-            resources: allResources,
+        const { collection } = options;
+        const resources = collection === undefined
+            ? registry.getAllResources()
+            : registry.getAllResources().filter((r) => r.collections?.includes(collection) ?? false);
+        const report = buildScanReport({
+            resources,
             root: projectRoot,
-            lane,
-            extentSource,
+            lane: population.lane,
+            extentSource: extentSourceOf(population),
             durationMs: Date.now() - startTime,
-            collections: collectionsOutput,
+            collections: collectionCounts(registry.getCollectionStats(), collection),
             verbose: options.verbose ?? false,
         });
-        writeStructuredOutput(payload, options.format);
-        process.exit(ExitCode.OK);
+        endWithReport('resources scan', report, format);
     }
     catch (error) {
-        handleCommandError(error, logger, startTime, 'Scan', options.format);
+        endWithRefusal('resources scan', refusalCodeOf(error), error, format, { strict: false }, NOTHING_FINISHED);
     }
 }
 //# sourceMappingURL=scan.js.map

package/dist/commands/resources/scan.js.map

@@ -1 +1 @@
-{"version":3,"file":"scan.js","sourceRoot":"","sources":["../../../src/commands/resources/scan.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"scan.js","sourceRoot":"","sources":["../../../src/commands/resources/scan.ts"],"names":[],"mappings":"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"}