reslock
Deterministic resource lockfile and integrity manifest toolkit for MoonBit asset pipelines.
moonbit
assets
fingerprint
manifest
wasm
resource-pipeline
moon add WSH-ai-nb/reslock@0.1.0
Download zipAuthor
Version
0.1.0
License
MIT
Repository
Last updated
18 hours ago
Downloads
3
README#reslock
reslock 是一个 MoonBit 原生资源锁文件与完整性清单库，用于给 WebAssembly 应用、小游戏、静态站点和资源管线生成可复现的资源清单。它把资源路径、类型、字节长度、内容指纹、缓存策略和标签导出为稳定的 .reslock 文本格式，并提供解析、校验、摘要和 diff 能力。
#解决的问题
资源文件在构建、部署和缓存过程中经常发生隐式变化。reslock 让项目可以在发布前固定资源状态，检查路径是否安全、清单是否可复现、缓存策略是否合理，并在两个版本之间生成新增、删除和变更报告。
#适用场景
- MoonBit Wasm 前端和小游戏资源清单；
- 静态资源、教学项目、示例工程的发布前校验；
- CI 中检查资源路径、重复条目和指纹变更；
- 需要稳定文本格式的资源管线、缓存清单或审计记录。
#安装
发布到 Mooncakes 后可使用：
moon add WSH-ai-nb/reslock本地开发时在项目中引用：
import {
"WSH-ai-nb/reslock" @reslock
}#最小示例
let style = @reslock.asset(
"public\\css\\app.css",
"body{color:#24313f}",
kind=@reslock.Text,
tags=["css", "critical"],
).unwrap()
let manifest = @reslock.manifest("site-assets", "1.0.0", [style])
let lockfile = @reslock.render_manifest(manifest)
let parsed = @reslock.parse_manifest(lockfile).unwrap()
let summary = @reslock.summarize(parsed)
println(summary.manifest_fingerprint)#本地运行
moon check
moon build
moon test
moon run cmd/main示例入口会生成内置资源清单、解析回读、输出 seal 摘要，并执行一次 no-change diff。
#核心功能
- asset：从路径和内容构造资源条目，自动规范化路径、计算 FNV-1a 64 位指纹、规范化标签；
- sealed_asset：从已有字节长度和指纹恢复条目，适合导入外部管线结果；
- normalize_path：拒绝绝对路径、父目录穿越和不可导出的路径片段；
- path_info：拆解资源路径的目录、文件名、扩展名、深度和隐藏文件状态；
- render_manifest / parse_manifest：稳定导出和解析 .reslock 文本格式；
- validate_manifest / is_valid：检查空清单、重复路径、非法指纹、非法标签、缓存策略风险；
- diff_manifest / render_diff：生成新增、删除、变更的资源差异报告；
- catalog_manifest：按目录、扩展名、资源类型、缓存策略、标签和资产桶生成统计目录；
- assess_quality：输出质量分、风险等级、缓存策略建议和可读 findings；
- evaluate_release_gate：按照发布门禁判断当前清单可直接发布、带警告发布或应阻断；
- summarize_release_delta：把两个清单之间的 diff 归纳为 patch / minor / major 影响；
- summarize：输出条目数、总字节数、清单指纹、错误数和警告数。
#支持范围
- 文本内容的资源条目构造；
- 路径规范化和安全路径校验；
- 稳定 .reslock v1 文本格式；
- FNV-1a 64 位非加密内容指纹；
- 资源清单校验、摘要、diff 和 CLI smoke 示例；
- 路径画像、资产分类、目录统计、质量评分和发布门禁；
- 纯 MoonBit 实现，仅依赖 MoonBit core。
#暂不支持范围
- 直接扫描文件系统；
- 加密级哈希或签名；
- 压缩、打包、上传和 CDN 发布；
- 二进制文件读取；
- Mooncakes 登录与正式发布自动化。
#测试与验收
moon check
moon build
moon test
moon run cmd/main
moon publish --dry-runmoon publish --dry-run 需要先确认 moon.mod 中的 Mooncakes owner 与当前登录账号一致，并完成 Mooncakes 登录。
#Mooncakes 包名
WSH-ai-nb/reslock#许可证与参考说明
本项目采用 MIT 许可证。核心实现为原创 MoonBit 代码，不移植第三方源码，不包含来源不明素材；哈希算法使用公开的 FNV-1a 思路重新实现，仅作为非加密完整性指纹。
#Asset
pub(all) struct Asset {
path : String
kind : AssetKind
bytes : Int
fingerprint : String
policy : CachePolicy
tags : Array[String]
note : String?
} derive(Eq)One resource entry inside a deterministic resource lockfile.
#AssetBucket
pub(all) enum AssetBucket {
BucketSource
BucketDocument
BucketConfig
BucketMedia
BucketArchive
BucketGenerated
BucketRuntime
BucketOther
} derive(Eq)#AssetCatalog
#AssetKind
#CachePlan
pub(all) struct CachePlan {
path : String
current : CachePolicy
recommended : CachePolicy
tier : CacheTier
aligned : Bool
reason : String
} derive(Eq)#CachePolicy
Cache and deployment intent for an asset.
#CacheTier
pub(all) enum CacheTier {
CacheStable
CacheRefreshable
CacheTransient
CacheCallerManaged
} derive(Eq)#DiffKind
Diff category for comparing two manifests.
#DirectoryProfile
pub(all) struct DirectoryProfile {
directory : String
entries : Int
bytes : Int
generated_entries : Int
runtime_entries : Int
media_entries : Int
source_entries : Int
document_entries : Int
warnings : Int
} derive(Eq)#EntryDiff
A single manifest diff row.
#Finding
pub(all) struct Finding {
level : FindingLevel
code : String
path : String?
message : String
} derive(Eq)A validation finding with a stable machine-readable code.
#Manifest
A resource manifest. Entries are sorted only when exported, so callers may
preserve discovery order during construction.
#PathInfo
#PolicyAdvice
pub(all) struct PolicyAdvice {
path : String
current : CachePolicy
recommended : CachePolicy
reason : String
} derive(Eq)#PolicyProfile
pub(all) struct PolicyProfile {
total : Int
immutable : Int
revalidate : Int
no_store : Int
runtime : Int
aligned : Int
misaligned : Int
stability_score : Int
immutable_bytes : Int
revalidate_bytes : Int
no_store_bytes : Int
runtime_bytes : Int
} derive(Eq)#QualityReport
pub(all) struct QualityReport {
score : Int
risk : RiskLevel
entries : Int
total_bytes : Int
errors : Int
warnings : Int
generated_assets : Int
runtime_assets : Int
no_store_assets : Int
immutable_assets : Int
missing_tag_assets : Int
oversized_assets : Int
duplicate_fingerprint_assets : Int
directory_count : Int
extension_count : Int
policy_advice : Array[PolicyAdvice]
findings : Array[Finding]
} derive(Eq)#ReleaseDecision
#ReleaseDelta
pub(all) struct ReleaseDelta {
added : Int
removed : Int
changed : Int
byte_delta : Int
policy_changes : Int
kind_changes : Int
fingerprint_changes : Int
tag_changes : Int
impact : ReleaseImpact
} derive(Eq)#ReleaseGate
pub(all) struct ReleaseGate {
min_score : Int
allow_warnings : Bool
max_warnings : Int
max_entries : Int
max_total_bytes : Int
max_asset_bytes : Int
require_tags : Bool
forbid_runtime : Bool
forbid_no_store : Bool
require_readme_asset : Bool
require_license_asset : Bool
} derive(Eq)#ReleaseGateResult
pub(all) struct ReleaseGateResult {
decision : ReleaseDecision
quality : QualityReport
blockers : Array[String]
warnings : Array[String]
notes : Array[String]
} derive(Eq)#ReleaseImpact
#ReslockError
pub(all) enum ReslockError {
EmptyPath
AbsolutePath(String)
ParentTraversal(String)
InvalidPathSegment(String)
InvalidTag(String)
InvalidFingerprint(String)
DuplicatePath(String)
MissingHeader
InvalidLine(Int, String)
InvalidEscape(String)
BadNumber(String)
UnknownKind(String)
UnknownPolicy(String)
} derive(Eq)Errors returned by parsers and constructors.
#RiskLevel
#SealSummary
pub(all) struct SealSummary {
entries : Int
total_bytes : Int
manifest_fingerprint : String
errors : Int
warnings : Int
} derive(Eq)A compact, reproducible summary of a manifest.
#asset
fn asset(path : String, content : String, kind? : AssetKind, policy? : CachePolicy, tags? : Array[String], note? : String) -> Result[Asset, ReslockError]#assets_between_sizes
#assets_larger_than
#assets_requiring_revalidation
#assets_smaller_than
#assets_under_directory
#assets_with_bucket
#assets_with_extension
#assets_with_policy
#catalog_fingerprint_index
#directories_with_warnings
#duplicate_fingerprint_rows
#evaluate_default_release_gate
#evaluate_release_gate
#evaluate_strict_release_gate
#gate_with_size_budget
fn gate_with_size_budget(gate : ReleaseGate, max_total_bytes : Int, max_asset_bytes : Int) -> ReleaseGate#manifest_release_notes
#path_with_extension
#path_without_extension
#policy_advice_for_manifest
#profile_directory
#release_delta_from_diffs
#release_impact
fn release_impact(added : Int, removed : Int, changed : Int, policy_changes : Int, kind_changes : Int) -> ReleaseImpact#render_directory_profiles
#sealed_asset
fn sealed_asset(path : String, kind : AssetKind, bytes : Int, fingerprint : String, policy : CachePolicy, tags? : Array[String], note? : String) -> Result[Asset, ReslockError]#summarize_release_delta
Deterministic resource lockfile and integrity manifest toolkit for MoonBit asset pipelines.
moonbitassetsfingerprintmanifestwasmresource-pipeline
0.1.0
MIT
Updated 18 hours ago
3 downloads