refactor: complete explicit app sdk migration

+labkit/+app/+diagnostic/Artifact.m

@@ -0,0 +1,99 @@
+classdef (Sealed) Artifact
+    %ARTIFACT Describe one anonymous diagnostic-sample artifact.
+    %
+    % Usage:
+    %   artifact = labkit.app.diagnostic.Artifact( ...
+    %       id,role,relativePath,Name=Value)
+    %
+    % Description:
+    %   Identifies one synthetic input, expected export, or support file
+    %   beneath a diagnostic sample root without exposing a user file path.
+    %
+    % Inputs:
+    %   id - Nonempty semantic identifier unique within a SamplePack.
+    %   role - Nonempty App-owned artifact purpose.
+    %   relativePath - Nonempty diagnostic-root-relative path without
+    %       traversal.
+    %
+    % Optional Name-Value Arguments:
+    %   Expectation - "loads", "rejects", "exports", or "support".
+    %       Default: "loads".
+    %
+    % Outputs:
+    %   artifact - Immutable diagnostic artifact value.
+    %
+    % Errors:
+    %   labkit:app:contract:UnknownArgument - An option is unknown,
+    %       duplicated, or unpaired.
+    %   labkit:app:contract:InvalidValue - Text, path, or Expectation is
+    %       malformed.
+    %
+    % Example:
+    %   artifact = labkit.app.diagnostic.Artifact( ...
+    %       "input","source","samples/input.csv");
+    %   assert(artifact.Expectation == "loads")
+    %
+    % See also labkit.app.diagnostic.SampleContext,
+    %   labkit.app.diagnostic.SamplePack
+
+    properties (SetAccess = immutable)
+        Id (1, 1) string
+        Role (1, 1) string
+        RelativePath (1, 1) string
+        Expectation (1, 1) string
+    end
+
+    methods
+        function obj = Artifact(id, role, relativePath, varargin)
+            options = labkit.app.internal.OptionParser.parse( ...
+                "labkit.app.diagnostic.Artifact", "Expectation", ...
+                varargin{:});
+            obj.Id = nonemptyText(id, "Id");
+            obj.Role = nonemptyText(role, "Role");
+            obj.RelativePath = relativePathValue(relativePath);
+            expectation = optionValue(options, "Expectation", "loads");
+            expectation = nonemptyText(expectation, "Expectation");
+            if ~any(expectation == ...
+                    ["loads", "rejects", "exports", "support"])
+                error("labkit:app:contract:InvalidValue", ...
+                    "Diagnostic Artifact Expectation is unsupported.");
+            end
+            obj.Expectation = expectation;
+        end
+    end
+end
+
+function value = relativePathValue(value)
+value = replace(nonemptyText(value, "RelativePath"), "\", "/");
+if startsWith(value, "/") || startsWith(value, "//") || ...
+        ~isempty(regexp(char(value), '^[A-Za-z]:', "once"))
+    invalid("RelativePath must be diagnostic-root-relative.");
+end
+parts = split(value, "/");
+if any(parts == ["", ".", ".."], "all")
+    invalid("RelativePath must not traverse diagnostic boundaries.");
+end
+value = join(parts, "/");
+end
+
+function value = nonemptyText(value, name)
+if ~(ischar(value) || (isstring(value) && isscalar(value)))
+    invalid("%s must be scalar text.", name);
+end
+value = string(value);
+if strlength(value) == 0
+    invalid("%s must be nonempty.", name);
+end
+end
+
+function value = optionValue(options, name, defaultValue)
+value = defaultValue;
+if isfield(options, name)
+    value = options.(name);
+end
+end
+
+function invalid(message, varargin)
+error("labkit:app:contract:InvalidValue", ...
+    "Diagnostic Artifact " + message, varargin{:});
+end

+labkit/+app/+diagnostic/Options.m

@@ -0,0 +1,86 @@
+classdef (Sealed) Options
+    %OPTIONS Configure one App SDK diagnostic session.
+    %
+    % Usage:
+    %   options = labkit.app.diagnostic.Options()
+    %   options = labkit.app.diagnostic.Options(Name=Value)
+    %
+    % Description:
+    %   Options selects standard or verbose runtime recording and whether a
+    %   Definition should build its declared anonymous synthetic sample.
+    %   Omitting Diagnostics from Definition.launch is equivalent to the
+    %   default standard options. This value never exposes a runtime,
+    %   recorder, figure registry, or callback transport.
+    %
+    % Optional Name-Value Arguments:
+    %   Level - "standard" or "verbose". Standard keeps a bounded in-memory
+    %       diagnostic history; verbose additionally writes structured
+    %       artifacts when ArtifactFolder is nonempty. Default: "standard".
+    %   ArtifactFolder - Scalar diagnostic-session folder. Empty keeps
+    %       recording in memory only. Default: "".
+    %   Sample - "none" or "synthetic". Synthetic requires the Definition's
+    %       BuildDebugSample contract. Default: "none".
+    %
+    % Outputs:
+    %   options - Immutable diagnostic configuration.
+    %
+    % Errors:
+    %   labkit:app:contract:UnknownArgument - An option is unknown,
+    %       duplicated, or unpaired.
+    %   labkit:app:contract:InvalidValue - A supplied value is malformed or
+    %       outside its documented legal set.
+    %
+    % Example:
+    %   options = labkit.app.diagnostic.Options(Level="verbose");
+    %   assert(options.Level == "verbose")
+    %
+    % See also labkit.app.Definition,
+    %   labkit.app.diagnostic.SampleContext,
+    %   labkit.app.diagnostic.SamplePack
+
+    properties (SetAccess = immutable)
+        Level (1, 1) string
+        ArtifactFolder (1, 1) string
+        Sample (1, 1) string
+    end
+
+    methods
+        function obj = Options(varargin)
+            names = ["Level", "ArtifactFolder", "Sample"];
+            options = labkit.app.internal.OptionParser.parse( ...
+                "labkit.app.diagnostic.Options", names, varargin{:});
+            obj.Level = oneOf(optionValue( ...
+                options, "Level", "standard"), ...
+                ["standard", "verbose"], "Level");
+            obj.ArtifactFolder = scalarText(optionValue( ...
+                options, "ArtifactFolder", ""), "ArtifactFolder");
+            obj.Sample = oneOf(optionValue( ...
+                options, "Sample", "none"), ...
+                ["none", "synthetic"], "Sample");
+        end
+    end
+end
+
+function value = oneOf(value, legal, name)
+value = scalarText(value, name);
+if ~any(value == legal)
+    error("labkit:app:contract:InvalidValue", ...
+        "Diagnostic Options %s must be %s.", ...
+        name, strjoin(legal, " or "));
+end
+end
+
+function value = scalarText(value, name)
+if ~(ischar(value) || (isstring(value) && isscalar(value)))
+    error("labkit:app:contract:InvalidValue", ...
+        "Diagnostic Options %s must be scalar text.", name);
+end
+value = string(value);
+end
+
+function value = optionValue(options, name, defaultValue)
+value = defaultValue;
+if isfield(options, name)
+    value = options.(name);
+end
+end

+labkit/+app/+diagnostic/SampleContext.m

@@ -0,0 +1,162 @@
+classdef (Sealed) SampleContext
+    %SAMPLECONTEXT Provide bounded folders for anonymous debug samples.
+    %
+    % Usage:
+    %   context = labkit.app.diagnostic.SampleContext(artifactFolder)
+    %   filepath = context.samplePath(relativePath)
+    %   filepath = context.outputPath(relativePath)
+    %   record = context.sourceRecord(id,role,filepath,required)
+    %   artifact = context.artifact(id,role,filepath,Name=Value)
+    %
+    % Description:
+    %   SampleContext creates one diagnostic root with samples and outputs
+    %   children. App-owned BuildDebugSample callbacks may write only
+    %   anonymous synthetic files beneath these folders. The value does not
+    %   expose a runtime, recorder, project store, or UI object.
+    %
+    % Inputs:
+    %   artifactFolder - Nonempty scalar diagnostic-session folder.
+    %   relativePath - Nonempty child path without an absolute root, empty
+    %       segment, current segment, or parent traversal.
+    %   id - Stable portable-source identifier.
+    %   role - Stable portable-source role.
+    %   filepath - Path returned by samplePath.
+    %   required - Logical scalar source requirement.
+    %
+    % Outputs:
+    %   context - Immutable diagnostic sample context.
+    %   filepath - Absolute path bounded by SampleFolder or OutputFolder.
+    %   record - Portable source value from
+    %       labkit.app.project.sourceRecord.
+    %   artifact - Typed diagnostic artifact whose relative path is derived
+    %       from a filepath beneath ArtifactFolder.
+    %
+    % Errors:
+    %   labkit:app:contract:InvalidValue - A folder, relative path, or source
+    %       argument is malformed.
+    %   MATLAB filesystem errors propagate when the diagnostic folders cannot
+    %       be created.
+    %
+    % Typical Call:
+    %   context = labkit.app.diagnostic.SampleContext(tempname);
+    %   filepath = context.samplePath("input.csv");
+    %
+    % See also labkit.app.diagnostic.Artifact,
+    %   labkit.app.diagnostic.SamplePack,
+    %   labkit.app.project.sourceRecord
+
+    properties (SetAccess = immutable)
+        ArtifactFolder (1, 1) string
+        SampleFolder (1, 1) string
+        OutputFolder (1, 1) string
+    end
+
+    methods
+        function obj = SampleContext(artifactFolder)
+            artifactFolder = nonemptyText( ...
+                artifactFolder, "ArtifactFolder");
+            obj.ArtifactFolder = artifactFolder;
+            obj.SampleFolder = string(fullfile( ...
+                char(artifactFolder), "samples"));
+            obj.OutputFolder = string(fullfile( ...
+                char(artifactFolder), "outputs"));
+            ensureFolder(obj.ArtifactFolder);
+            ensureFolder(obj.SampleFolder);
+            ensureFolder(obj.OutputFolder);
+        end
+
+        function filepath = samplePath(obj, relativePath)
+            filepath = boundedPath(obj.SampleFolder, relativePath);
+        end
+
+        function filepath = outputPath(obj, relativePath)
+            filepath = boundedPath(obj.OutputFolder, relativePath);
+        end
+
+        function record = sourceRecord(~, id, role, filepath, required)
+            if nargin < 5
+                required = true;
+            end
+            record = labkit.app.project.sourceRecord( ...
+                id, role, filepath, required);
+        end
+
+        function artifact = artifact(obj, id, role, filepath, varargin)
+            relativePath = relativeArtifactPath( ...
+                obj.ArtifactFolder, filepath);
+            artifact = labkit.app.diagnostic.Artifact( ...
+                id, role, relativePath, varargin{:});
+        end
+    end
+end
+
+function filepath = boundedPath(folder, relativePath)
+relativePath = replace(nonemptyText(relativePath, "relativePath"), "\", "/");
+if startsWith(relativePath, "/") || startsWith(relativePath, "//") || ...
+        ~isempty(regexp(char(relativePath), '^[A-Za-z]:', "once"))
+    invalid("relativePath must be folder-relative.");
+end
+parts = split(relativePath, "/");
+if any(parts == ["", ".", ".."], "all")
+    invalid("relativePath must not traverse the diagnostic folder.");
+end
+partCells = cellstr(parts);
+filepath = string(fullfile(char(folder), partCells{:}));
+parent = string(fileparts(filepath));
+ensureFolder(parent);
+end
+
+function ensureFolder(folder)
+if exist(char(folder), "dir") ~= 7
+    mkdir(char(folder));
+end
+end
+
+function relativePath = relativeArtifactPath(root, filepath)
+root = normalizedAbsolutePath(root, "ArtifactFolder");
+filepath = normalizedAbsolutePath(filepath, "filepath");
+rootPrefix = root + "/";
+if ispc
+    inside = startsWith(lower(filepath), lower(rootPrefix));
+else
+    inside = startsWith(filepath, rootPrefix);
+end
+if ~inside
+    invalid("filepath must remain beneath ArtifactFolder.");
+end
+relativePath = extractAfter(filepath, strlength(rootPrefix));
+if strlength(relativePath) == 0
+    invalid("filepath must name a child artifact.");
+end
+end
+
+function value = normalizedAbsolutePath(value, name)
+value = replace(nonemptyText(value, name), "\", "/");
+if ~isAbsolutePath(value)
+    value = replace(string(fullfile(pwd, char(value))), "\", "/");
+end
+while endsWith(value, "/") && value ~= "/" && ...
+        isempty(regexp(char(value), '^[A-Za-z]:/$', "once"))
+    value = extractBefore(value, strlength(value));
+end
+end
+
+function tf = isAbsolutePath(value)
+tf = startsWith(value, "/") || startsWith(value, "//") || ...
+    ~isempty(regexp(char(value), '^[A-Za-z]:/', "once"));
+end
+
+function value = nonemptyText(value, name)
+if ~(ischar(value) || (isstring(value) && isscalar(value)))
+    invalid("%s must be scalar text.", name);
+end
+value = string(value);
+if strlength(value) == 0
+    invalid("%s must be nonempty.", name);
+end
+end
+
+function invalid(message, varargin)
+error("labkit:app:contract:InvalidValue", ...
+    "Diagnostic SampleContext " + message, varargin{:});
+end