changeledger 0.10.0 → 0.11.0

package/bin/changeledger.mjs

@@ -201,7 +201,7 @@ program
       '',
       'When --id is omitted, the single in-progress change is used automatically;',
       'zero or multiple in-progress changes require --id explicitly. Repeat --id',
-      'for a multi-id subject: each id gets its own bracket ([#A] [#B]).',
+      'for a multi-id commit: the clean subject gets a ChangeLedger: [#A] [#B] body.',
       '',
       'Examples:',
       '  changeledger commit -m "feat(cli): add helper"',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "changeledger",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Turn conversations into buildable changes.",
   "type": "module",
   "bin": {

package/src/commands/check.mjs

@@ -41,7 +41,7 @@ function checkCommits(args, commitsIdx, cwd, output, json) {
 
   const errors = violations.map((v) => ({
     file: '(commits)',
-    message: `${v.sha} missing [#id] marker: "${v.subject}"`,
+    message: `${v.sha} ${v.reason}: "${v.subject}"`,
   }));
 
   if (json) {

package/src/commands/commit.mjs

@@ -33,7 +33,12 @@ export function commit({ message, ids = [] } = {}, cwd = process.cwd(), run = mu
     resolvedIds = [active[0].frontmatter.id];
   }
 
-  const subject = `${message} ${resolvedIds.map((id) => `[#${id}]`).join(' ')}`;
-  run(['commit', '-m', subject], repo.repoRoot);
+  const markers = resolvedIds.map((id) => `[#${id}]`).join(' ');
+  const multiple = resolvedIds.length > 1;
+  const subject = multiple ? message : `${message} ${markers}`;
+  const args = multiple
+    ? ['commit', '-m', subject, '-m', `ChangeLedger: ${markers}`]
+    : ['commit', '-m', subject];
+  run(args, repo.repoRoot);
   return subject;
 }

package/src/config-migration.mjs

@@ -4,7 +4,7 @@ import { parseDocument } from 'yaml';
 import { writeFileAtomic } from './atomic-write.mjs';
 import { templatesDir } from './paths.mjs';
 
-export const SUPPORTED_SCHEMA_VERSION = 2;
+export const SUPPORTED_SCHEMA_VERSION = 3;
 
 const CANONICAL_STATUSES = [
   'draft',
@@ -76,7 +76,8 @@ export function buildMigration(originalText) {
   if (current < 1) {
     migrateToV1(doc, config, changes);
   }
-  migrateToV2(doc, config, changes);
+  if (current < 2) migrateToV2(doc, config, changes);
+  if (current < 3) migrateToV3(doc, config, changes);
 
   // No line wrapping and no flow padding: keeps untouched flow sequences
   // (statuses, stages) byte-identical to their common written form.
@@ -164,6 +165,28 @@ function migrateToV2(doc, config, changes) {
   }
 }
 
+// 2 → 3: expose Git integration without inventing a repository-specific branch.
+// Existing git settings and comments remain byte-for-byte owned by the source doc.
+function migrateToV3(doc, config, changes) {
+  if (!Object.hasOwn(config, 'git')) {
+    setBlankGitSection(doc);
+    changes.push('added git section');
+  }
+}
+
+function setBlankGitSection(doc) {
+  const gitNode = parseDocument('git:\n  integration_branch:\n').get('git', true);
+  doc.set('git', gitNode);
+  const gitPair = doc.contents.items.find(
+    (pair) => pair.key?.value === 'git' || pair.key === 'git',
+  );
+  if (!gitPair) return;
+  if (typeof gitPair.key === 'string') gitPair.key = doc.createNode(gitPair.key);
+  gitPair.key.spaceBefore = true;
+  gitPair.key.commentBefore =
+    ' Git integration: change branches start from and merge into this branch';
+}
+
 // Apply migration to a file (or dry-run). Returns summary string.
 export function applyMigration(configFile, { dryRun = false } = {}) {
   let original;

package/src/git.mjs

@@ -5,6 +5,7 @@
 import { execFileSync } from 'node:child_process';
 
 const SEP = String.fromCharCode(31); // ASCII unit separator — safe field delimiter
+const RECORD_SEP = String.fromCharCode(30);
 
 // Repo-location env vars git itself exports while running a hook (e.g. this
 // project's own pre-commit). Left inherited, a child `git` call would silently
@@ -111,36 +112,53 @@ export function defaultBaseBranch(repoRoot, run = defaultRun) {
   );
 }
 
-// Commits in `range` (e.g. `main..HEAD`): sha, subject and whether each is a
-// merge (more than one parent) — the git metadata `check --commits` lints.
+// Commits in `range` (e.g. `main..HEAD`): sha, subject, body and whether each is
+// a merge (more than one parent) — the git metadata `check --commits` lints.
 export function commitsInRange(repoRoot, range, run = defaultRun) {
   let out;
   try {
-    out = run(['log', range, `--pretty=format:%H${SEP}%P${SEP}%s`], repoRoot);
+    out = run(['log', range, `--pretty=format:%H${SEP}%P${SEP}%s${SEP}%b${RECORD_SEP}`], repoRoot);
   } catch (e) {
     throw new Error(`git log failed for range "${range}": ${e.message}`);
   }
   return out
-    .split('\n')
+    .split(RECORD_SEP)
+    .map((record) => record.trim())
     .filter(Boolean)
-    .map((line) => {
-      const [sha, parents, subject] = line.split(SEP);
+    .map((record) => {
+      const [sha, parents, subject, body = ''] = record.split(SEP);
       return {
         sha,
         subject,
+        body: body.trim(),
         isMerge: parents.trim().split(/\s+/).filter(Boolean).length > 1,
       };
     });
 }
 
-// A well-formed marker is one or more `[#id]` groups, each separated by a
-// single space, terminating the subject — the canonical multi-id shape is
-// separate brackets (`[#A] [#B]`), never a comma list in one bracket.
-const MARKER_RE = /(\[#[^\]\s]+\])(\s\[#[^\]\s]+\])*$/;
+const MARKER_RE = /\[#[^\]\s]+\]$/;
+const ANY_MARKER_RE = /\[#[^\]\s]+\]/g;
+const MULTI_BODY_RE = /^ChangeLedger: (\[#[^\]\s]+\])( \[#[^\]\s]+\])+$/;
+
 export function hasCommitMarker(subject) {
   return MARKER_RE.test(subject.trim());
 }
 
+function commitMarkerViolation({ subject, body }) {
+  const subjectMarkers = subject.match(ANY_MARKER_RE) ?? [];
+  const trimmedBody = body.trim();
+  const hasBodyLabel = trimmedBody.includes('ChangeLedger:');
+  const validMultiBody = MULTI_BODY_RE.test(trimmedBody);
+
+  if (subjectMarkers.length > 1) return 'multiple [#id] markers must be in the body';
+  if (hasBodyLabel && !validMultiBody) return 'malformed ChangeLedger body';
+  if (subjectMarkers.length === 1 && hasCommitMarker(subject) && !hasBodyLabel) return null;
+  if (subjectMarkers.length === 0 && validMultiBody) return null;
+  if (subjectMarkers.length === 1 && validMultiBody)
+    return 'ambiguous [#id] markers in both subject and body';
+  return 'missing [#id] marker';
+}
+
 // Lints `range`: every non-merge commit must carry a well-formed `[#id]`
 // marker, except `chore(release)` prep commits. Returns only the violations
 // (sha + subject); never throws for a clean range.
@@ -150,8 +168,8 @@ export function lintCommitRange(repoRoot, range, run = defaultRun) {
   for (const c of commits) {
     if (c.isMerge) continue;
     if (/^chore\(release\):/.test(c.subject)) continue;
-    if (!hasCommitMarker(c.subject))
-      violations.push({ sha: c.sha.slice(0, 7), subject: c.subject });
+    const reason = commitMarkerViolation(c);
+    if (reason) violations.push({ sha: c.sha.slice(0, 7), subject: c.subject, reason });
   }
   return violations;
 }

package/src/viewer/domain.mjs

@@ -468,6 +468,7 @@ const PATCH_ALLOWED = new Set([
   'readiness',
   'types',
   'release',
+  'git',
 ]);
 
 const CANONICAL_STATUSES_REQUIRED = new Set([
@@ -500,6 +501,8 @@ function applyPatch(doc, patch, currentConfig) {
       applyReleasePatch(doc, value);
     } else if (key === 'readiness') {
       applyReadinessPatch(doc, value);
+    } else if (key === 'git') {
+      applyGitPatch(doc, value);
     } else if (key === 'statuses') {
       applyRequiredListPatch(doc, 'statuses', value, CANONICAL_STATUSES_REQUIRED);
     } else if (key === 'stages') {
@@ -554,3 +557,12 @@ function applyReadinessPatch(doc, readinessPatch) {
     doc.setIn(['readiness', 'verification_patterns'], readinessPatch.verification_patterns);
   }
 }
+
+function applyGitPatch(doc, gitPatch) {
+  if (!gitPatch || typeof gitPatch !== 'object') return;
+  if (typeof gitPatch.integration_branch === 'string' && gitPatch.integration_branch.trim()) {
+    doc.setIn(['git', 'integration_branch'], gitPatch.integration_branch.trim());
+  } else if (gitPatch.integration_branch === null) {
+    doc.deleteIn(['git', 'integration_branch']);
+  }
+}

package/src/viewer/public/app.js

@@ -1094,6 +1094,14 @@ function formEditorTemplate(config) {
       </label>
     </fieldset>
 
+    <fieldset class="config-group">
+      <legend>Git</legend>
+      <label>Integration branch
+        <input name="integration_branch" .value=${cfg.git?.integration_branch ?? ''} placeholder="Auto-detect" />
+      </label>
+      <p class="config-note">Change branches start from and merge into this branch. Leave empty to auto-detect.</p>
+    </fieldset>
+
     <fieldset class="config-group">
       <legend>Lifecycle statuses</legend>
       <label>Status order (one per line)
@@ -1339,6 +1347,13 @@ export function collectFormPatch(formEl, currentConfig) {
   if (els.specs_dir && els.specs_dir.value !== (currentConfig.specs_dir ?? '.changeledger/specs')) {
     patch.specs_dir = els.specs_dir.value;
   }
+  if (els.integration_branch) {
+    const currentBranch = currentConfig.git?.integration_branch ?? '';
+    const proposedBranch = els.integration_branch.value.trim();
+    if (proposedBranch !== currentBranch) {
+      patch.git = { integration_branch: proposedBranch || null };
+    }
+  }
 
   const statuses = listFromControl(els.statuses);
   if (els.statuses && !sameList(statuses, currentConfig.statuses ?? [])) patch.statuses = statuses;

package/templates/config.yml

@@ -3,7 +3,7 @@
 
 # Schema version — used to detect and migrate outdated configurations.
 # Run `changeledger config migrate --dry-run` to inspect available migrations.
-schema_version: 2
+schema_version: 3
 
 # Language for generated documentation CONTENT. Structure (headings, keys, enums)
 # is always English. See `changeledger context spec`.
@@ -35,6 +35,10 @@ release:
 changes_dir: .changeledger/changes
 specs_dir: .changeledger/specs
 
+# Git integration: change branches start from and merge into this branch
+git:
+  integration_branch:
+
 # Valid lifecycle statuses (order = progress)
 statuses: [draft, approved, in-progress, in-review, in-validation, blocked, done, discarded]
 

package/templates/contract/implement.md

@@ -37,15 +37,17 @@ Commit messages use the canonical shape:
 feat(scope): description [#20260629-234939]
 ```
 
-Use the actual change id and the appropriate conventional type. Referencing more
-than one change is separate brackets, one per id (`[#A] [#B]`) — never a comma
-list inside one bracket. Ledger meta-commits (status, review, log, archive)
-carry the marker like any other commit; only merge commits and `chore(release)`
-prep are exempt. `changeledger commit -m "<type>(<scope>): <desc>" [--id <id>]...`
-composes and creates the commit for you: it resolves the single `in-progress`
-change automatically when `--id` is omitted, and fails without committing if
-that is ambiguous or the subject isn't conventional. `changeledger check
---commits [<base>]` lints `<base>..HEAD` for the marker with the same
+Use the actual change id and the appropriate conventional type. One change keeps
+its marker at the end of the subject. Referencing more than one change keeps the
+subject clean and puts separate brackets in one canonical body line:
+`ChangeLedger: [#A] [#B]` — never a comma list in one bracket. Ledger
+meta-commits (status, review, log, archive) carry markers like any other commit;
+only merge commits and `chore(release)` prep are exempt. `changeledger commit -m
+"<type>(<scope>): <desc>" [--id <id>]...` composes and creates the commit for
+you: it resolves the single `in-progress` change automatically when `--id` is
+omitted, and fails without committing if that is ambiguous or the subject isn't
+conventional. `changeledger check --commits [<base>]` lints `<base>..HEAD` for
+either canonical marker placement with the same
 exemptions — run it before requesting review. If shared files make a combined commit
 unavoidable, record it in Log or the handoff and name every change sharing the
 surface.