@hegemonart/get-design-done 1.52.0 → 1.54.0

package/scripts/lib/mappers/incremental-discover.d.cts

@@ -0,0 +1,133 @@
+// scripts/lib/mappers/incremental-discover.d.cts — types for incremental-discover.cjs (Phase 53 DISC-01).
+//
+// Mirrors the .d.cts sidecar convention used by concurrency-tuner.cjs so the
+// .ts explore-parallel-runner can import planIncremental without a TS7016
+// implicit-any. The runtime module is dep-free CJS (it dynamic-import()s the
+// .mjs batchers + the .ts fingerprint engine internally).
+
+/** A community batch (the A-subsystem `computeBatches` shape). */
+export interface Batch {
+  id: string;
+  members: string[];
+  mergeable: boolean;
+  kind: 'code' | 'token' | 'motion' | 'a11y' | 'misc';
+  source: 'louvain' | 'fallback' | 'subsplit' | 'merge';
+}
+
+/** A single per-node fingerprint-compare entry fed to the classifier. */
+export interface CompareResult {
+  id: string;
+  type?: string;
+  change: 'NONE' | 'COSMETIC' | 'STRUCTURAL';
+}
+
+/** The change-classifier result (sdk/fingerprint/classify.cjs). */
+export interface Classification {
+  action: 'SKIP' | 'PARTIAL_UPDATE' | 'ARCHITECTURE_UPDATE' | 'FULL_UPDATE';
+  structuralCount: number;
+  pct: number;
+  dirChanged: boolean;
+  majorRestructure: boolean;
+  affectedBatchHints: string[];
+  reason: string;
+  thresholds: { fullFileCount: number; fullPct: number; archPctMax: number };
+}
+
+/** A per-node fingerprint pair plus its node type, as persisted to the store. */
+export interface StoredFingerprint {
+  full: string;
+  structural: string;
+  type?: string;
+}
+
+/** The neighborMap sidecar for one batch (neighbor-map.mjs shape). */
+export interface NeighborMap {
+  batchId: string | null;
+  neighbors: Record<string, unknown[]>;
+  truncated: Record<string, { omitted: number }>;
+}
+
+/** Options bag for planIncremental. */
+export interface PlanIncrementalOptions {
+  /** The `--full` opt-out: force a FULL re-map regardless of the classifier. */
+  forceFull?: boolean;
+  /** Forwarded to computeBatches (resolution, maxCommunitySize, configCwd, …). */
+  computeBatchesOpts?: unknown;
+  /** buildNeighborMap cap (default 50). */
+  neighborCap?: number;
+  /** Forwarded into classify's projectStats.thresholds. */
+  thresholds?: unknown;
+  /** Force the bootstrap signal off when the store had a snapshot but it was empty. */
+  hadPriorBaseline?: boolean;
+}
+
+/** The incremental plan returned by planIncremental. */
+export interface IncrementalPlan {
+  action: 'SKIP' | 'PARTIAL_UPDATE' | 'ARCHITECTURE_UPDATE' | 'FULL_UPDATE';
+  batches: Batch[];
+  batchesToMap: Batch[];
+  neighborMaps: Record<string, NeighborMap>;
+  fingerprints: Record<string, StoredFingerprint>;
+  compareResults: CompareResult[];
+  classification: Classification;
+  method: 'louvain' | 'count-fallback';
+  modularity: number | null;
+}
+
+/** A DirShape derived from node-id provenance. */
+export interface DirShape {
+  dirs: string[];
+  counts: Record<string, number>;
+  layerHist: Record<string, number>;
+}
+
+/**
+ * Plan an incremental discover/explore cycle: compute community batches, run the
+ * change classifier against the prior fingerprint snapshot, and elect which
+ * batches to re-map (SKIP=[], PARTIAL=affected, FULL=all). Async (it
+ * dynamic-import()s the .mjs batchers + the .ts fingerprint engine).
+ */
+export function planIncremental(args: {
+  graph: unknown;
+  prevFingerprints?: unknown;
+  opts?: PlanIncrementalOptions;
+}): Promise<IncrementalPlan>;
+
+/** Pure batch-selection matrix: SKIP→[], FULL→all, PARTIAL/ARCH→hint intersection. */
+export function selectBatches(
+  batches: Batch[],
+  action: string,
+  affectedBatchHints: string[],
+): Batch[];
+
+/** Derive the current DirShape (+ totalFiles) from a graph's file-nodes. */
+export function deriveDirShape(
+  graph: unknown,
+): DirShape & { totalFiles: number };
+
+/** Reconstruct the prior DirShape from a prevFingerprints map (null when empty). */
+export function derivePrevDirShape(
+  prevFingerprints: unknown,
+): DirShape | null;
+
+/** Build current fingerprints + the compareResults change set for a graph. */
+export function buildCompareResults(
+  graph: unknown,
+  prevFingerprints: unknown,
+  fingerprint: (input: unknown, type: string) => { full: string; structural: string },
+  compareFingerprints: (
+    a: { full: string; structural: string } | null,
+    b: { full: string; structural: string } | null,
+  ) => string,
+): { fingerprints: Record<string, StoredFingerprint>; compareResults: CompareResult[] };
+
+/** Project one fingerprintable node into its per-type fingerprint input. */
+export function projectNode(node: unknown, fpType: string, idx: unknown): unknown;
+
+/** Build the once-per-graph relationship index used by projectNode. */
+export function indexForProjection(
+  graph: unknown,
+): { byId: Map<string, unknown>; tokensOf: Map<string, Set<string>>; variantsOf: Map<string, Set<string>> };
+
+/** The graph node `type` values that are independently fingerprinted. */
+export const FINGERPRINTABLE: Map<string, string>;

package/scripts/lib/new-addendum.cjs

@@ -0,0 +1,204 @@
+'use strict';
+/**
+ * scripts/lib/new-addendum.cjs — Phase 54 (Composable Reference Addendums), REG-01.
+ *
+ * Pure, dependency-free generator behind the `/gdd:new-addendum <kind> <name>`
+ * scaffolder skill (source/skills/new-addendum/SKILL.md). The SKILL.md drives
+ * the prompts; this module is the deterministic core it (and the test suite)
+ * call. Mirrors scripts/lib/manifest/scaffolder.cjs (the Phase 50 skill
+ * scaffolder): same ReDoS-safe NAME_RE, same throw-on-invalid contract, same
+ * "render a skeleton string, never touch the manifest" boundary.
+ *
+ * A stack addendum is a REGISTRY ENTRY, not a skill (CONTEXT R4). This
+ * scaffolder writes ONE reference/{systems|frameworks|motion}/<name>.md file
+ * with the locked frontmatter + the 4 mandatory sections. It does NOT touch
+ * reference/registry.json (the maintainer/orchestrator adds the entry + runs
+ * the registry round-trip), exactly as new-skill does not touch skills.json.
+ *
+ * Exports:
+ *   buildAddendumRecord({ kind, name, composesInto }) -> a normalized record
+ *     { name, kind, composes_into, phase, dir, path }. Validates kind against
+ *     KINDS and name against NAME_RE; defaults composes_into by kind. Throws on
+ *     invalid input.
+ *   renderAddendumMd(record) -> the addendum skeleton string (frontmatter +
+ *     the 4 mandatory sections: Conventions / File patterns / Gotchas /
+ *     Example output). Em-dash-free (lint:prose-clean).
+ *   targetPathFor(kind, name) -> the repo-root-relative path the file is
+ *     written to (e.g. "reference/systems/<name>.md").
+ *
+ * Dependency-free of any third party (node:path only; no fs writes here — the
+ * SKILL.md writes the rendered string with the Write tool, same as new-skill).
+ */
+
+// Slug rule mirrors scripts/lib/manifest/scaffolder.cjs NAME_RE and the
+// registry.schema.json entry-name pattern: kebab-case, starts alnum,
+// ^[a-z0-9][a-z0-9-._]*$. The `\w`-free char class is linear-time (no ReDoS).
+const NAME_RE = /^[a-z0-9][a-z0-9-._]*$/;
+
+// The three addendum categories (CONTEXT R4 / shared contracts). Maps each
+// kind to its reference subdir and the default composes_into mapper list.
+// The defaults mirror the round-1 addendum frontmatter that executors C/D/E
+// shipped (systems + frameworks vs motion), so a scaffolded addendum is wired
+// the same way the hand-authored ones are.
+const KIND_SPEC = {
+  system: {
+    dir: 'reference/systems',
+    composesInto: ['token-mapper', 'component-taxonomy-mapper'],
+    label: 'design-system',
+  },
+  framework: {
+    dir: 'reference/frameworks',
+    composesInto: ['component-taxonomy-mapper', 'visual-hierarchy-mapper'],
+    label: 'framework',
+  },
+  motion: {
+    dir: 'reference/motion',
+    composesInto: ['motion-mapper'],
+    label: 'motion library',
+  },
+};
+
+const KINDS = Object.keys(KIND_SPEC);
+const PHASE = 54;
+
+function fail(msg) {
+  throw new Error(`new-addendum: ${msg}`);
+}
+
+/** Normalize a composes_into input (string or array) to a clean mapper list. */
+function normalizeComposesInto(composesInto) {
+  if (composesInto == null) return undefined;
+  let parts;
+  if (Array.isArray(composesInto)) parts = composesInto;
+  else if (typeof composesInto === 'string') parts = composesInto.split(',');
+  else fail('composesInto must be an array or comma-separated string of mapper names');
+  const cleaned = parts.map((s) => String(s).trim()).filter(Boolean);
+  if (cleaned.length === 0) return undefined;
+  // Mapper names follow the same slug rule as everything else here.
+  for (const m of cleaned) {
+    if (!NAME_RE.test(m)) fail(`composesInto entry "${m}" is not a valid mapper slug`);
+  }
+  // De-dupe, preserve first-seen order.
+  return [...new Set(cleaned)];
+}
+
+/** Repo-root-relative target path for a (kind, name). Throws on invalid kind/name. */
+function targetPathFor(kind, name) {
+  const spec = KIND_SPEC[kind];
+  if (!spec) fail(`kind "${kind}" must be one of: ${KINDS.join(', ')}`);
+  const n = typeof name === 'string' ? name.trim() : name;
+  if (!n || typeof n !== 'string' || !NAME_RE.test(n)) {
+    fail(`name "${name}" must match ${NAME_RE} (lower-case, starts alnum, kebab/dot/underscore)`);
+  }
+  return `${spec.dir}/${n}.md`;
+}
+
+/**
+ * Build a normalized addendum record from scaffolder inputs.
+ * @param {{ kind: string, name: string, composesInto?: string|string[] }} input
+ * @returns {{ name, kind, composes_into: string[], phase: number, dir: string, path: string }}
+ * @throws on an invalid kind, an invalid name, or a malformed composesInto.
+ */
+function buildAddendumRecord(input) {
+  const opts = input || {};
+  const kind = typeof opts.kind === 'string' ? opts.kind.trim().toLowerCase() : opts.kind;
+  if (!kind || typeof kind !== 'string' || !KIND_SPEC[kind]) {
+    fail(`kind is required and must be one of: ${KINDS.join(', ')}`);
+  }
+  const name = typeof opts.name === 'string' ? opts.name.trim() : opts.name;
+  if (!name || typeof name !== 'string') fail('name is required (a kebab-case slug)');
+  if (!NAME_RE.test(name)) {
+    fail(`name "${name}" must match ${NAME_RE} (lower-case, starts alnum, kebab/dot/underscore)`);
+  }
+
+  const spec = KIND_SPEC[kind];
+  const composesInto = normalizeComposesInto(opts.composesInto) || spec.composesInto.slice();
+
+  return {
+    name,
+    kind,
+    composes_into: composesInto,
+    phase: PHASE,
+    dir: spec.dir,
+    path: `${spec.dir}/${name}.md`,
+  };
+}
+
+/**
+ * Render the addendum skeleton string for a record.
+ * Frontmatter keys are emitted in the canonical order the round-1 addendums
+ * use (name, kind, composes_into, phase). The body carries the 4 mandatory
+ * sections (Conventions / File patterns / Gotchas / Example output) with TODO
+ * placeholders + a vendor-attribution comment slot (house style). Em-dash-free.
+ * @param {object} record  a buildAddendumRecord result (or raw {kind,name,...})
+ */
+function renderAddendumMd(record) {
+  if (!record || typeof record !== 'object') fail('renderAddendumMd requires a record object');
+  // Validate / normalize defensively so renderAddendumMd(buildAddendumRecord(x))
+  // and renderAddendumMd(rawObject) both produce a contract-valid file.
+  const rec = buildAddendumRecord({
+    kind: record.kind,
+    name: record.name,
+    composesInto: record.composes_into,
+  });
+
+  const title = rec.name
+    .split(/[-._]/)
+    .filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(' ');
+
+  const composes = `[${rec.composes_into.join(', ')}]`;
+
+  const lines = [
+    '---',
+    `name: ${rec.name}`,
+    `kind: ${rec.kind}`,
+    `composes_into: ${composes}`,
+    `phase: ${rec.phase}`,
+    '---',
+    `<!-- Vendor docs: TODO add the canonical ${rec.kind} documentation URL. -->`,
+    '',
+    `# ${title}`,
+    '',
+    '## Conventions',
+    '',
+    `- TODO: how this ${rec.kind} names and structures its tokens and components.`,
+    '- TODO: the one rule a mapper most often gets wrong here.',
+    '',
+    '## File patterns',
+    '',
+    '- TODO: the config files and source-file shapes that identify this stack.',
+    `- Identify via: TODO the detectStack signal (dep name or config file) for ${rec.name}.`,
+    '',
+    '## Gotchas',
+    '',
+    '- TODO: the usage that looks like a token but is not (flag as an anti-pattern node).',
+    '- TODO: a unit or naming trap a mapper must not mis-classify.',
+    '',
+    '## Example output',
+    '',
+    '```json',
+    '{',
+    '  "schema_version": "52.0",',
+    '  "nodes": [',
+    '    { "id": "tok.color.primary", "type": "token", "subtype": "color", "name": "TODO", "summary": "TODO brand primary token.", "complexity": "simple", "tags": ["color", "brand"] }',
+    '  ],',
+    '  "edges": []',
+    '}',
+    '```',
+    '',
+  ];
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  buildAddendumRecord,
+  renderAddendumMd,
+  targetPathFor,
+  NAME_RE,
+  KINDS,
+  KIND_SPEC,
+  PHASE,
+};