@software-dlc/cli 0.157.2

package/dist/local/guide-commands.d.ts

@@ -0,0 +1,79 @@
+import { type C4NodeGuideData } from '@software-dlc/graph/types';
+import { z } from 'zod';
+type GuideState = {
+    label: string;
+    description?: string;
+    guide: C4NodeGuideData;
+};
+/** The hash an export records of the guide it came from. */
+export declare function guideStateHash(state: GuideState): string;
+export declare function createGuide(input: {
+    projection_dir: string;
+    journey: string;
+    label: string;
+    description?: string;
+    node_id?: string;
+}): Promise<{
+    version: number;
+    status: string;
+    node_id: string;
+    journey: string;
+    steps: number;
+    edge_id: string;
+}>;
+declare const guide_export_schema: z.ZodObject<{
+    schema_version: z.ZodLiteral<1>;
+    node_id: z.ZodString;
+    source_hash: z.ZodString;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    steps: z.ZodArray<z.ZodUnknown>;
+}, z.core.$strict>;
+export type GuideExport = z.infer<typeof guide_export_schema>;
+export declare function exportGuide(input: {
+    projection_dir: string;
+    node_id: string;
+}): Promise<{
+    steps: import("@software-dlc/graph/types").C4GuideEndUserStep[];
+    description?: string | undefined;
+    schema_version: 1;
+    node_id: string;
+    source_hash: string;
+    label: string;
+}>;
+export declare function parseGuideExport(value: unknown): GuideExport;
+export declare function updateGuide(input: {
+    projection_dir: string;
+    node_id: string;
+    file: GuideExport;
+}): Promise<{
+    version: number;
+    status: string;
+    node_id: string;
+    steps: number;
+}>;
+export declare function validateGuide(input: {
+    projection_dir: string;
+    node_id: string;
+}): Promise<{
+    version: number;
+    node_id: string;
+    publishable: boolean;
+    problems: import("@software-dlc/graph/validator").GuidePublishProblem[];
+}>;
+export declare function listGuides(input: {
+    projection_dir: string;
+}): Promise<{
+    version: number;
+    guides: {
+        id: string;
+        title: string;
+        audience: "end_users" | null;
+        journey: string | null;
+        journey_label: string | null;
+        steps: number;
+        state: "draft";
+    }[];
+}>;
+export {};
+//# sourceMappingURL=guide-commands.d.ts.map

package/dist/local/guide-commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guide-commands.d.ts","sourceRoot":"","sources":["../../src/local/guide-commands.ts"],"names":[],"mappings":"AAMA,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,2BAA2B,CAAC;AASlF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA8DxB,KAAK,UAAU,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,eAAe,CAAA;CAAE,CAAC;AAElF,4DAA4D;AAC5D,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAWxD;AAiCD,wBAAsB,WAAW,CAAC,KAAK,EAAE;IACvC,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;;;;;;;GAqEA;AAED,QAAA,MAAM,mBAAmB;;;;;;;kBASd,CAAC;AAEZ,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAE9D,wBAAsB,WAAW,CAAC,KAAK,EAAE;IAAE,cAAc,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE;;;;;;;GAYnF;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAE5D;AASD,wBAAsB,WAAW,CAAC,KAAK,EAAE;IACvC,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,WAAW,CAAC;CACnB;;;;;GA8CA;AAED,wBAAsB,aAAa,CAAC,KAAK,EAAE;IAAE,cAAc,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE;;;;;GAKrF;AAED,wBAAsB,UAAU,CAAC,KAAK,EAAE;IAAE,cAAc,EAAE,MAAM,CAAA;CAAE;;;;;;;;;;;GAwBjE"}

package/dist/local/guide-commands.js

@@ -0,0 +1,247 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { readdir, readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { stringifyCanonicalJson } from '@software-dlc/graph/computation';
+import { c4_node_guide_data_schema } from '@software-dlc/graph/schema';
+import { C4_GUIDE_LIMITS } from '@software-dlc/graph/types';
+import { buildJourneys, getSiblingNodeLabelBucket, guidePublishProblems, validateGuides } from '@software-dlc/graph/validator';
+import { z } from 'zod';
+import { createDocumentNode, linkDocumentNode } from './document-commands.js';
+import { writeJsonAtomically } from './projection.js';
+async function readEntities(directory) {
+    let names;
+    try {
+        names = await readdir(directory);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    return Promise.all(names
+        .filter((name) => name.endsWith('.json'))
+        .sort()
+        .map(async (name) => JSON.parse(await readFile(join(directory, name), 'utf8'))));
+}
+async function readProjection(projection_dir) {
+    const nodes = await readEntities(join(projection_dir, 'nodes'));
+    const edges = await readEntities(join(projection_dir, 'edges'));
+    return { nodes, edges, nodes_by_id: new Map(nodes.map((node) => [node.id, node])) };
+}
+const nodePath = (projection_dir, node_id) => join(projection_dir, 'nodes', `${node_id}.json`);
+function requireGuide(nodes_by_id, node_id) {
+    const node = nodes_by_id.get(node_id);
+    if (!node)
+        throw new Error(`No node ${node_id} in this projection.`);
+    if (node.type !== 'document' || node.data.data.guide === undefined) {
+        throw new Error(`Node ${node_id} is ${node.type === 'document' ? 'a Document without a guide' : `a ${node.type}`}, not a guide.`);
+    }
+    const parsed = c4_node_guide_data_schema.safeParse(node.data.data.guide);
+    if (!parsed.success) {
+        throw new Error(`Guide ${node_id} has guide data this version cannot edit: ${parsed.error.issues[0]?.message ?? 'schema mismatch'}`);
+    }
+    return { node, guide: parsed.data };
+}
+/** The hash an export records of the guide it came from. */
+export function guideStateHash(state) {
+    const digest = createHash('sha256')
+        .update(stringifyCanonicalJson({
+        label: state.label,
+        description: state.description ?? null,
+        guide: state.guide
+    }))
+        .digest('hex');
+    return `sha256:${digest}`;
+}
+function stateOf(node, guide) {
+    const data = node.data.data;
+    return {
+        label: data.label ?? '',
+        ...(data.description !== undefined ? { description: data.description } : {}),
+        guide
+    };
+}
+/** Refuses a title another root Document already has, as the validator would at commit. */
+function refuseTakenTitle(nodes, node_id, label, nothing_changed) {
+    const bucket = getSiblingNodeLabelBucket({
+        id: node_id,
+        type: 'document',
+        data: { data: { label } }
+    });
+    const same = nodes.find((node) => node.id !== node_id && getSiblingNodeLabelBucket(node) === bucket);
+    if (same) {
+        throw new Error(`Document ${same.id} already has the title "${label}"; choose another.${nothing_changed}`);
+    }
+}
+export async function createGuide(input) {
+    const { nodes, edges } = await readProjection(input.projection_dir);
+    const journeys = buildJourneys({ nodes, edges });
+    const journey = journeys.journeys.find((candidate) => candidate.entry === input.journey);
+    if (!journey) {
+        throw new Error(`${input.journey} is not a journey entry. Entries: ${journeys.journeys.map((j) => `${j.entry} (${j.label})`).join(', ') || 'none'}.`);
+    }
+    if (journey.stories.length > C4_GUIDE_LIMITS.steps) {
+        throw new Error(`Journey "${journey.label}" has ${journey.stories.length} stories; a guide has at most ${C4_GUIDE_LIMITS.steps} steps.`);
+    }
+    if (!input.label.trim())
+        throw new Error('A guide needs a title (--label).');
+    const node_id = input.node_id ?? randomUUID();
+    refuseTakenTitle(nodes, node_id, input.label, '');
+    const guide = c4_node_guide_data_schema.parse({
+        schema_version: 1,
+        audience: 'end_users',
+        journey: journey.entry,
+        steps: journey.stories.map((story, index) => ({
+            id: `step-${index + 1}`,
+            title: '',
+            instruction: '',
+            source_story: story
+        }))
+    });
+    await createDocumentNode({
+        projection_dir: input.projection_dir,
+        node_id,
+        outline: {
+            schema_version: 1,
+            label: input.label,
+            ...(input.description !== undefined ? { description: input.description } : {}),
+            entries: [
+                {
+                    id: 'notes',
+                    prose: `Notes for authors of this guide to journey "${journey.label}". They are never published.`
+                }
+            ]
+        }
+    });
+    const path = nodePath(input.projection_dir, node_id);
+    let link;
+    try {
+        const raw = JSON.parse(await readFile(path, 'utf8'));
+        raw.data.data.guide = guide;
+        await writeJsonAtomically(path, raw);
+        link = await linkDocumentNode({
+            projection_dir: input.projection_dir,
+            node_id,
+            target_id: journey.entry
+        });
+    }
+    catch (error) {
+        // A guide without its describes edge is never left behind.
+        await rm(path, { force: true });
+        throw error;
+    }
+    return {
+        version: 1,
+        status: 'created',
+        node_id,
+        journey: journey.entry,
+        steps: guide.steps.length,
+        edge_id: link.edge_id
+    };
+}
+const guide_export_schema = z
+    .object({
+    schema_version: z.literal(1),
+    node_id: z.string().min(1),
+    source_hash: z.string().regex(/^sha256:[0-9a-f]{64}$/),
+    label: z.string().refine((label) => label.trim().length > 0, 'label must not be empty'),
+    description: z.string().optional(),
+    steps: z.array(z.unknown())
+})
+    .strict();
+export async function exportGuide(input) {
+    const { nodes_by_id } = await readProjection(input.projection_dir);
+    const { node, guide } = requireGuide(nodes_by_id, input.node_id);
+    const state = stateOf(node, guide);
+    return {
+        schema_version: 1,
+        node_id: input.node_id,
+        source_hash: guideStateHash(state),
+        label: state.label,
+        ...(state.description !== undefined ? { description: state.description } : {}),
+        steps: guide.steps
+    };
+}
+export function parseGuideExport(value) {
+    return guide_export_schema.parse(value);
+}
+/** The step a schema issue path points into, by the file's own step id. */
+function stepNamed(file, path) {
+    if (path[0] !== 'steps' || typeof path[1] !== 'number')
+        return 'the guide';
+    const step = file.steps[path[1]];
+    return typeof step?.id === 'string' ? `step ${step.id}` : `step ${path[1] + 1}`;
+}
+export async function updateGuide(input) {
+    const { nodes, nodes_by_id } = await readProjection(input.projection_dir);
+    const { node, guide } = requireGuide(nodes_by_id, input.node_id);
+    if (input.file.node_id !== input.node_id) {
+        throw new Error(`This file was exported from guide ${input.file.node_id}, not ${input.node_id}; nothing changed.`);
+    }
+    if (input.file.source_hash !== guideStateHash(stateOf(node, guide))) {
+        throw new Error(`Guide ${input.node_id} changed since this file was exported; export it again with sdlc workspace guide export ${input.node_id} and reapply your edits. Nothing changed.`);
+    }
+    refuseTakenTitle(nodes, input.node_id, input.file.label, ' Nothing changed.');
+    // The audience and the journey are kept; only steps come from the file.
+    const parsed = c4_node_guide_data_schema.safeParse({ ...guide, steps: input.file.steps });
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        throw new Error(`${stepNamed(input.file, issue.path)}: ${issue.message} (at ${issue.path.join('.')}); nothing changed.`);
+    }
+    const errors = validateGuides({
+        nodes: [{ ...node, data: { ...node.data, data: { ...node.data.data, guide: parsed.data } } }],
+        edges: []
+    }).filter((issue) => issue.status === 'broken');
+    if (errors.length) {
+        throw new Error(`${errors.map((issue) => issue.message).join(' ')} Nothing changed.`);
+    }
+    const { label: _label, description: _description, guide: _guide, ...other } = node.data.data;
+    const next = {
+        ...other,
+        label: input.file.label,
+        ...(input.file.description !== undefined ? { description: input.file.description } : {}),
+        guide: parsed.data
+    };
+    if (stringifyCanonicalJson(next) === stringifyCanonicalJson(node.data.data)) {
+        return { version: 1, status: 'unchanged', node_id: input.node_id, steps: parsed.data.steps.length };
+    }
+    // The content changes, so its stored object hash no longer applies.
+    const { object_hash: _stale, ...data } = node.data;
+    await writeJsonAtomically(nodePath(input.projection_dir, input.node_id), {
+        ...node,
+        data: { ...data, data: next }
+    });
+    return { version: 1, status: 'updated', node_id: input.node_id, steps: parsed.data.steps.length };
+}
+export async function validateGuide(input) {
+    const { nodes, edges, nodes_by_id } = await readProjection(input.projection_dir);
+    requireGuide(nodes_by_id, input.node_id);
+    const problems = guidePublishProblems({ nodes, edges }, input.node_id);
+    return { version: 1, node_id: input.node_id, publishable: problems.length === 0, problems };
+}
+export async function listGuides(input) {
+    const { nodes, edges, nodes_by_id } = await readProjection(input.projection_dir);
+    const journeys = new Map(buildJourneys({ nodes, edges }).journeys.map((j) => [j.entry, j]));
+    const guides = nodes
+        .filter((node) => node.type === 'document' && node.data.data.guide != null)
+        .map((node) => {
+        const guide = node.data.data.guide;
+        const journey = typeof guide.journey === 'string' ? guide.journey : null;
+        return {
+            id: node.id,
+            title: node.data.data.label ?? '',
+            audience: guide.audience ?? null,
+            journey,
+            journey_label: journey
+                ? (journeys.get(journey)?.label ??
+                    nodes_by_id.get(journey)?.data.data.label ??
+                    null)
+                : null,
+            steps: Array.isArray(guide.steps) ? guide.steps.length : 0,
+            // Every guide is a draft until publishing exists (mg-publish).
+            state: 'draft'
+        };
+    });
+    return { version: 1, guides };
+}
+//# sourceMappingURL=guide-commands.js.map

package/dist/local/guide-commands.js.map

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

package/dist/local/health-files.d.ts

@@ -0,0 +1,24 @@
+import type { HealthReason } from './health-schema.js';
+export declare class HealthInspectionError extends Error {
+    readonly code: HealthReason;
+    constructor(code: HealthReason);
+}
+/** No cache, mkdir, lock acquisition, symlink traversal or content in diagnostics. */
+export declare class HealthFiles {
+    private readonly directories;
+    private readonly stamps;
+    stamp(path: string): Promise<string>;
+    observe(path: string): Promise<boolean>;
+    read(path: string, max_bytes?: number): Promise<string | null>;
+    readPrefix(path: string, length: number, max_bytes: number): Promise<Buffer | null>;
+    private readBytes;
+    regular(path: string, max_bytes: number): Promise<void>;
+    /** Bound directory enumeration and retain entry identity for the final recheck. */
+    entries(path: string): Promise<{
+        name: string;
+        is_file: boolean;
+    }[]>;
+    private list;
+    changed(): Promise<boolean>;
+}
+//# sourceMappingURL=health-files.d.ts.map

package/dist/local/health-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health-files.d.ts","sourceRoot":"","sources":["../../src/local/health-files.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,qBAAa,qBAAsB,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAE,YAAY;gBAAlB,IAAI,EAAE,YAAY;CAGxC;AAED,sFAAsF;AACtF,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IACzD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;IAC9C,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA6BpC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAWvC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,SAAc,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAInE,UAAU,CACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;YAGX,SAAS;IAsCjB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM7D,mFAAmF;IAC7E,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;YAS5D,IAAI;IAkBZ,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;CAOlC"}

package/dist/local/health-files.js

@@ -0,0 +1,133 @@
+import { constants } from 'node:fs';
+import { lstat, open, opendir } from 'node:fs/promises';
+import { dirname, parse } from 'node:path';
+import { checkOperation, currentOperation } from './operation.js';
+export class HealthInspectionError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}
+/** No cache, mkdir, lock acquisition, symlink traversal or content in diagnostics. */
+export class HealthFiles {
+    directories = new Map();
+    stamps = new Map();
+    async stamp(path) {
+        checkOperation();
+        try {
+            const value = await lstat(path, { bigint: true });
+            if (value.isSymbolicLink())
+                throw new HealthInspectionError('state_unavailable');
+            return (value.isDirectory()
+                ? [value.dev, value.ino, value.mode]
+                : [
+                    value.dev,
+                    value.ino,
+                    value.mode,
+                    value.size,
+                    value.mtimeNs,
+                    value.ctimeNs
+                ]).join(':');
+        }
+        catch (error) {
+            if (typeof error === 'object' &&
+                error &&
+                'code' in error &&
+                error.code === 'ENOENT')
+                return 'missing';
+            throw error;
+        }
+    }
+    async observe(path) {
+        // Observe ancestors too so a replaced directory invalidates dependent facts.
+        const parent = dirname(path);
+        if (parent !== parse(path).root && !this.stamps.has(parent))
+            await this.observe(parent);
+        const stamp = await this.stamp(path);
+        if (!this.stamps.has(path))
+            this.stamps.set(path, stamp);
+        else if (this.stamps.get(path) !== stamp)
+            throw new HealthInspectionError('changed_during_read');
+        return stamp !== 'missing';
+    }
+    async read(path, max_bytes = 1024 * 1024) {
+        const bytes = await this.readBytes(path, max_bytes, max_bytes + 1);
+        return bytes === null ? null : bytes.toString('utf8');
+    }
+    async readPrefix(path, length, max_bytes) {
+        return this.readBytes(path, max_bytes, length);
+    }
+    async readBytes(path, max_bytes, read_bytes) {
+        if (!(await this.observe(path)))
+            return null;
+        await this.regular(path, max_bytes);
+        const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+            const stat = await file.stat();
+            if (!stat.isFile() || stat.size > max_bytes)
+                throw new HealthInspectionError('state_unavailable');
+            // Fixed-sized read prevents a concurrently growing file from defeating the budget.
+            const bytes = Buffer.alloc(read_bytes);
+            let offset = 0;
+            while (offset < bytes.length) {
+                checkOperation();
+                const { bytesRead } = await file.read(bytes, offset, bytes.length - offset, offset);
+                if (bytesRead === 0)
+                    break;
+                offset += bytesRead;
+            }
+            currentOperation()?.signal.throwIfAborted();
+            if (offset > max_bytes)
+                throw new HealthInspectionError('state_unavailable');
+            await this.observe(path);
+            return bytes.subarray(0, offset);
+        }
+        finally {
+            await file.close();
+        }
+    }
+    async regular(path, max_bytes) {
+        await this.observe(path);
+        const stat = await lstat(path);
+        if (!stat.isFile() || stat.size > max_bytes)
+            throw new HealthInspectionError('state_unavailable');
+    }
+    /** Bound directory enumeration and retain entry identity for the final recheck. */
+    async entries(path) {
+        await this.observe(path);
+        const entries = await this.list(path);
+        const stamp = JSON.stringify(entries);
+        if (!this.directories.has(path))
+            this.directories.set(path, stamp);
+        else if (this.directories.get(path) !== stamp)
+            throw new HealthInspectionError('changed_during_read');
+        return entries;
+    }
+    async list(path) {
+        const stat = await lstat(path);
+        if (!stat.isDirectory())
+            throw new HealthInspectionError('state_unavailable');
+        const entries = [];
+        const directory = await opendir(path);
+        for await (const entry of directory) {
+            checkOperation();
+            if (entries.length >= 2000)
+                throw new HealthInspectionError('projection_limit_exceeded');
+            if (entry.isSymbolicLink())
+                throw new HealthInspectionError('state_unavailable');
+            entries.push({ name: entry.name, is_file: entry.isFile() });
+        }
+        return entries.sort((a, b) => a.name.localeCompare(b.name));
+    }
+    async changed() {
+        for (const [path, stamp] of this.directories)
+            if (JSON.stringify(await this.list(path)) !== stamp)
+                return true;
+        for (const [path, stamp] of this.stamps)
+            if ((await this.stamp(path)) !== stamp)
+                return true;
+        return false;
+    }
+}
+//# sourceMappingURL=health-files.js.map

package/dist/local/health-files.js.map

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

package/dist/local/health-inspection.d.ts

@@ -0,0 +1,12 @@
+import { type LocalHealthReport } from './health-schema.js';
+import { OperationError } from './operation.js';
+/** Internal source/config/store observation. No adapter dispatch or capability/action policy yet. */
+export declare function inspectLocalHealth(input: {
+    cwd: string;
+    env?: Readonly<Record<string, string | undefined>>;
+    timeout_ms?: number;
+    inspection?: 'context' | 'status';
+    signal?: AbortSignal;
+    on_cleanup_timeout?: (error: OperationError) => void;
+}): Promise<LocalHealthReport>;
+//# sourceMappingURL=health-inspection.d.ts.map

package/dist/local/health-inspection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health-inspection.d.ts","sourceRoot":"","sources":["../../src/local/health-inspection.ts"],"names":[],"mappings":"AAiBA,OAAO,EAEL,KAAK,iBAAiB,EAEvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAIL,cAAc,EAEf,MAAM,gBAAgB,CAAC;AAwMxB,qGAAqG;AACrG,wBAAsB,kBAAkB,CAAC,KAAK,EAAE;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAClC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,kBAAkB,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;CACtD,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAiP7B"}