@sdd-method/author-cli 0.16.1 → 0.16.2

package/dist/lib/snapshot/land.js

@@ -6,7 +6,11 @@
 //   - a member observed after the set date;
 //   - a prior member absent from the export and not declared carried (with a
 //     reason) or removed (with a reason) — never left to be inferred;
-//   - a member re-exported at the same revision whose bytes differ;
+//   - a member re-exported at the same revision whose bytes differ, unless the only
+//     difference is files under a path declared --not-source (with a reason) that the
+//     prior export holds and the new one does not: analysis a tool wrote into the old
+//     export, not the repository. The prior baseline is never edited, the excused files
+//     and the reason are recorded, and a declaration that excuses nothing is refused;
 //   - no recorded credential scan, or one with findings but no disposition —
 //     a snapshot owner often cannot remediate upstream code, so findings land
 //     with the disposition on the record, never as a false `clean`;
@@ -68,6 +72,17 @@ export async function land(inputs, write) {
         const s = splitFolder(m.exported_folder_name);
         return s ? [[s.stem, m.canonical_repo_key]] : [];
     }));
+    const notSource = new Map();
+    for (const [raw, reason] of inputs.notSource ?? []) {
+        const p = raw.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+        if (p === "" || p.startsWith("/") || p.split("/").includes(".."))
+            throw new SnapshotError(`--not-source '${raw}' must be a relative path inside a member folder`);
+        if (!reason.trim())
+            throw new SnapshotError(`--not-source ${raw} needs a reason: --not-source <path>=<why it is not source>`);
+        notSource.set(p, reason.trim());
+    }
+    const declaredPath = (f) => [...notSource.keys()].find((p) => f === p || f.startsWith(`${p}/`));
+    const excusedBy = new Map();
     const known = inputs.sddPath ? await knownRepositoryIds(inputs.sddPath) : new Set();
     const keyProblems = [];
     const members = [];
@@ -105,18 +120,35 @@ export async function land(inputs, write) {
             const before = await hashTree(memberBytesDir(areaRoot, prior, p));
             const after = await hashTree(join(dir, folder));
             const d = diffTrees(before, after);
-            const changed = d.added.length + d.removed.length + d.modified.length;
+            // Only a file the prior export holds and the new one lacks, under a declared path, is excused.
+            const excused = d.removed.filter((f) => declaredPath(f) !== undefined);
+            const changed = d.added.length + d.modified.length + d.removed.length - excused.length;
             if (changed > 0) {
-                throw new SnapshotError(`${key} was re-exported at the same revision ${revision} as ${prior.snapshot_id}, but ${changed} file(s) differ — one of the two exports is not what its name says`);
+                throw new SnapshotError(`${key} was re-exported at the same revision ${revision} as ${prior.snapshot_id}, but ${changed} file(s) differ — one of the two exports is not what its name says` +
+                    (notSource.size > 0 ? ` (--not-source excuses only files the prior export holds and this one does not, under a declared path)` : ""));
             }
             entry.reverified_at = md ?? id;
             entry.reverification = `re-exported at the same revision as ${prior.snapshot_id}; ${after.size} file(s) byte-identical`;
+            if (excused.length > 0) {
+                const byPath = new Map();
+                for (const f of excused) {
+                    const p = declaredPath(f);
+                    byPath.set(p, (byPath.get(p) ?? 0) + 1);
+                    excusedBy.set(p, (excusedBy.get(p) ?? 0) + 1);
+                }
+                entry.reverification += `; ${[...byPath].map(([p, n]) => `${n} file(s) under ${p}/ in ${prior.snapshot_id} only, not source: ${notSource.get(p)}`).join("; ")}`;
+                write(`note: ${key}: ${excused.length} file(s) under a --not-source path excused (prior export only)\n`);
+            }
         }
         members.push(entry);
     }
     if (keyProblems.length > 0) {
         throw new SnapshotError(`${keyProblems.length} derived key(s) are not repository ids:\n  - ${keyProblems.join("\n  - ")}`);
     }
+    const unused = [...notSource.keys()].filter((p) => !excusedBy.has(p));
+    if (unused.length > 0) {
+        throw new SnapshotError(`--not-source ${unused.join(", ")} excused nothing: no same-revision member's prior export holds files there that this one lacks; drop the declaration`);
+    }
     const removed = [];
     const unaccounted = [];
     for (const p of prior?.members ?? []) {

package/dist/maintain-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "0.17.1",
-  "built_against_sdd_cli": "5.3.1"
+  "version": "0.17.2",
+  "built_against_sdd_cli": "5.3.2"
 }

package/dist/verbs/snapshot.js

@@ -72,6 +72,7 @@ export function registerSnapshot(program) {
         .option("--role-hint <key=role>", "role_hint for a member; continuing members otherwise keep the prior baseline's (repeatable)", collectPairs, new Map())
         .option("--credential-scan <record>", "tool=…,version=…,date=YYYY-MM-DD,result=clean — or result=<findings>,disposition=<what, and why it stands>")
         .option("--notes <text>", "coherence caveats for the manifest")
+        .option("--not-source <path=reason>", "a path inside member folders that is not source (a folder a tool wrote into the prior export), and why: a same-revision re-export may lack it, recorded on the member; nothing else is excused (repeatable)", collectPairs, new Map())
         .action(async (area, o) => {
         const scan = record(o.credentialScan);
         exit(await runSnapshotLand({
@@ -85,6 +86,7 @@ export function registerSnapshot(program) {
             removed: o.removed,
             keys: o.key,
             roleHints: o.roleHint,
+            notSource: o.notSource,
             ...(scan ? { credentialScan: scan } : {}),
             ...(o.notes !== undefined ? { notes: o.notes } : {}),
         }, out));

package/dist/verify-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "5.3.1",
-  "built_against_sdd_cli": "5.3.1"
+  "version": "5.3.2",
+  "built_against_sdd_cli": "5.3.2"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sdd-method/author-cli",
-  "version": "0.16.1",
-  "sddCliVersion": "5.3.1",
+  "version": "0.16.2",
+  "sddCliVersion": "5.3.2",
   "description": "Re-author one SDD's content — scaffold, plan, contracts, conformance, api-surface, snapshots, briefings, catalogue check — plus every read-only verify verb. Ships only the code those verbs reach; it cannot sync the baseline or rebuild the catalogues. Maintenance is in @sdd-method/maintain-cli, administration in @sdd-method/sdd-cli.",
   "license": "UNLICENSED",
   "type": "module",