Skip to content

Releases

v3.0.0: intel anatomy maps the org's integrations

Choose a tag to compare

@cclabsnz cclabsnz released this 11 Oct 20:21

intel anatomy now maps an org's integrations. On a real Health Cloud sandbox,
anatomy-fragment.json carried 4 of 59 integration edges; it now carries 32, with the external
systems they reach as nodes. View A also stops drawing a refused read as a measured zero for a
user who cannot see setup.

This is a major because anatomy-fragment.json changes shape (docs/RELEASE.md): a new
integration node kind, integration edges from apexClass.* and org.root as well as products,
and no more anatomy.edges.remoteProxy coverage entry. It requires @cclabsnz/sf-core 0.9.0 or
later on whichever side merges the fragments, since the integration kind changed owner there.

Changed

  • anatomy-fragment.json carries most of the org's integrations, not 4 of 59. An integration
    edge used to need both a product and a Named Credential hop, so on a real Health Cloud sandbox 55
    of 59 were dropped. What changed:

    • The source is now the product the call was traced to; otherwise the Apex class making it
      (apexClass.*, the node intel map emits); otherwise, for a destination configured but never
      found being called, org.root.
    • The destination is a Named Credential (ncred.*) or a Remote Site Setting, emitted as a
      new integration.<SiteName> node. sf-core 0.9.0 gives sf-orgintel that kind.
    • Destinations are keyed by metadata names, never endpoint strings, so no external hostname
      enters the graph.

    On the sandbox: 32 integration links instead of 4, and 20 integration nodes. What's still left
    out is counted precisely.

    This changes anatomy-fragment.json's shape: new node kind, new edge sources, and the
    anatomy.edges.remoteProxy coverage entry is gone. It also requires @cclabsnz/sf-core
    0.9.0.

Fixed

  • A refusal no longer reads as a measured zero for a user who cannot see setup. Such a user
    cannot read Organization. For them:

    • "sObject type 'X' is not supported" is a failed read, not an absent feature;
    • a zero setup count is marked not read, while a non-zero count stands as a lower bound;
    • an empty platform-event list is marked not read.

    View A now draws those tiles hatched "not read" instead of a confident 0. Measured as a
    restricted user: the eight capability tiles and three ops tiles. Users who can see setup are
    unaffected.

  • 90-day record counts are taken for business objects only. Counting a custom metadata type by
    CreatedDate always fails, so every run that touched configuration reported false
    map.recordCounts failures (20 on a real sandbox). Configuration, events and setup objects are
    no longer counted.

v2.0.0: intel map describes the business model, not its plumbing

Choose a tag to compare

@cclabsnz cclabsnz released this 11 Oct 11:02

intel map now describes the org a Salesforce architect would recognise. It used to count every
pair of objects any Apex class or flow touched, test classes included, and to treat User,
RecordType and Share objects as peers of the business model. On a real Health Cloud sandbox it
reported 212 objects and 2,171 coupled pairs in 57 domains. This release reports 95 business
objects and 620 couplings in 17 domains, and states the rest as what those objects depend on.

This is a major because graph-fragment.json changes shape and meaning (docs/RELEASE.md).
If you read it:

  • couples edges join business objects only. For an unchanged org, expect fewer pairs and
    different endpoints.
  • Pairs with an actor, record type, setup object, configuration, event or reference data are
    new uses edges, each carrying attrs.roles.
  • Each touched object's role and its evidence arrive as attrs.orgintel.objectRole once
    merged, together with new map.objectRoles.* and map.apexClasses.tests coverage entries.

If you import the package, IntelContext.orgInfo is now OrgInfo | null. The HTML report of a
run with no roles decided is unchanged, byte for byte.

Changed

  • intel map classifies objects from platform evidence, and only business pairs are
    couplings.
    Each object this run touches gets a role from sf-core's classifyObject, decided
    from what the platform reports, never from its name:

    • describeGlobal's parent entity, plus layout and trigger capability;
    • the EntityDefinition sharing model;
    • what the OwnerId, CreatedById and RecordTypeId fields point at;
    • whether production automation only reads the object.

    What that changes:

    • Companions fold into their parent. AccountShare counts as Account.
    • Pairs with an actor, a record type, setup, configuration, an event or reference data are
      written as uses edges instead of couples, and the report states them in a new "What the
      business objects depend on" section.
    • Each object's role and its evidence are contributed as attrs.orgintel.objectRole.
    • A refused fact read degrades to unclassified, recorded under map.objectRoles.*. An
      unclassified object stays among the couplings.

    On a real Health Cloud sandbox, together with the test-class fix below, the map went from 212
    objects and 2,171 coupled pairs in 57 domains to 95 objects and 620 pairs in 17 domains, with
    User and RecordType out of the backbones. Expect couples counts, domains and backbones to
    change for an unchanged org.
    Specified in docs/OBJECT_ROLES_SPEC.md.

Fixed

  • Apex test classes are no longer analysed as production automation. A test class inserts
    fixture data for many objects at once, so its object references are not couplings in the running
    org. On a real Health Cloud sandbox 445 classes were tests, and excluding them took the map from
    2,171 coupled pairs to 1,231. A class is a test when the platform marks it so (the SymbolTable's
    IsTest annotation or testMethod modifier, or an @isTest class declaration in the body),
    never by name. Test classes are listed but not analysed, and reported once in the notes and as a
    map.apexClasses.tests coverage entry. Expect apexClassesAnalyzed and every coupling count
    to drop
    for an unchanged org.

  • "Top process backbones" in the terminal summary lists the heaviest couplings. It printed the
    first eight edges in id order, which on a real org meant weight-1 pairs whose names sorted first.

  • intel map and intel anatomy run for a user without View Setup and Configuration. Every
    command read Organization first, and the platform refuses that object to such a user, so the
    tool stopped before reading anything. That ruled out running it as the restricted users whose
    view of an org it exists to describe. Both commands now take the org id from the connection's
    auth info, name the org by its id, and say why in the run's notes. intel probe and
    intel discover report edition and sandbox status, which cannot be guessed, so they still
    stop, now naming the missing permission instead of printing the platform's bare
    sObject type 'Organization' is not supported. IntelContext.orgInfo is now OrgInfo | null.

  • intel anatomy reads Sites again. From 0.3.0 the channels collector queried
    SELECT Name, SiteName, Status FROM Site. Site has no SiteName column (the field belongs to
    RemoteProxy), so the read was refused with INVALID_FIELD on every org, and the channels band
    reported a failed read even where the org had sites. It now reads Name, MasterLabel and
    Status: MasterLabel is the label shown as the channel name, and Name, the site's unique
    technical name, keys the site.* node. The unit fixture had invented the missing column, which
    is how this shipped green; the new test's mock refuses any column Site does not have, as the
    org does. Found by running View A against a live org.

  • graph-fragment.json now marks what intel map dropped. The fragment hardcoded an empty
    coverage, so every drop the run detected reached the terminal and the HTML report and stopped
    there. Merged with intel anatomy's census, a refused FlowDefinitionView read looked the same
    as an org with no active flows: analysed.flows: 0 and nothing to explain it. Each drop is now
    also a coverage.unavailable entry, the same wiring anatomy-fragment.json already had.
    failed means the read was tried and refused. deferred means it was never tried.

    Scope Reason When
    map.flows failed the flow listing was refused
    map.flows.managed deferred managed-package flows, whose metadata is never requested
    map.flows.metadata failed one entry per flow whose metadata was refused, empty or unparseable
    map.flows.subflows deferred referenced subflows that were never retrieved, so their touches are not inherited
    map.apexClasses failed the class listing was refused
    map.apexClasses.unreadable failed classes with neither a readable body nor a SymbolTable
    map.apexTriggers failed the trigger listing was refused
    map.apexTriggers.unresolvedObject failed one entry per trigger whose object could not be resolved
    map.automationCounts.<field> failed a refused automation query, so that count is an unmeasured 0 on every object
    map.recordCounts deferred the sweep was capped by --max-node-counts
    map.recordCounts failed 90-day counts that were refused and fell back to 0
    map.objects failed the sObject catalog was refused

    Entries are sorted by scope, then reason, then detail, so the bytes stay stable across runs
    even though flow metadata is fetched concurrently. A run that drops nothing still writes an
    empty coverage.

  • Two silent fallbacks in intel map are now reported. A refused 90-day record count was
    stored as 0 with no note anywhere. A refused sObject catalog read meant running with no
    known-object set, which pushes every Apex class onto the regex fallback, also without a note.
    Both now appear in the run's notes and in the fragment's coverage.

v1.0.0: the legacy outputs are retired

Choose a tag to compare

@cclabsnz cclabsnz released this 23 Sep 04:59

sf intel map and sf intel anatomy now emit canonical graph fragments and nothing else. The three artifacts that preceded them are gone.

coupling-graph.json, landscape-manifest.json and anatomy.json were deprecated in 0.3.0, with the 0.x line announced as the migration window. This closes it.

Removed

  • The three artifacts are no longer written. intel map emits graph-fragment.json; intel anatomy emits anatomy-fragment.json. Both carry the same facts in a schema shared with sf-orgviz.
  • sf intel map --json no longer carries couplingGraph or manifest. This affects a different audience from the file readers: anyone scripting against the JSON output. Note the failure is quiet rather than loud — jq '.result.couplingGraph.edges | length' on the new payload prints 0 and exits 0. Read .result.fragment instead, which was already present in 0.3.0. Its couples edges carry the coupled pairs with their weight, operations, components and direction; its obj.* contributions carry the per-object figures.
  • MapArtifacts, AssembleInput and MapRunResult changed shape, which affects library importers rather than file readers.
  • Five landscape-manifest.json fields are withdrawn, not replaced: label, objects, metrics, graphRef and anchorObject. The navigation view reproduces the L0 and L1 coordinates, proven equivalent before the file was removed, and nothing else. All five are derivable from cluster membership and the per-object contributions, but no replacement was built and none is promised. If you consume one, open an issue describing the use and it will be built against that rather than guessed at.

Changed

  • renderMapHtml now takes a CouplingView. couplingViewOf is exported to obtain one from a fragment.
  • The interactive viewer builds its scene through the DOM API rather than assigning an HTML string, so no markup is reinterpreted at render time.

Unchanged, deliberately

The rendered HTML is byte-identical to 0.3.0, pinned by a golden captured while both render paths still existed. sf intel anatomy --json emits the same shape it always has: this release retires the file, not the payload.

Upgrading

If you read any of the three retired files, move to the fragments. If you script against sf intel map --json, read .result.fragment. If you import this package as a library, check the three types above. Everything else is unaffected.

v0.3.0: both commands project onto the canonical org graph

Choose a tag to compare

@cclabsnz cclabsnz released this 15 Sep 09:10

sf intel map and sf intel anatomy now emit their findings a second time as a canonical graph fragment, in the schema @cclabsnz/sf-orgviz also writes, so the two tools describe one org instead of two.

This release is additive. coupling-graph.json, landscape-manifest.json and anatomy.json are byte-identical to 0.2.0, pinned by golden tests, and a consumer that does not know about the fragments is unaffected.

Added

  • graph-fragment.json from sf intel map. The coupling analysis is unchanged; its output is now also rendered as a CanonicalGraph fragment. It carries no object nodes on purpose — sobject is a kind sf-orgviz owns and the merge refuses a fragment emitting a kind belonging to someone else — so couples edges stay unresolved until an extraction is merged in.
  • anatomy-fragment.json from sf intel anatomy, emitting only the three kinds this tool owns: site, product and ssoConfig. Personas, change data capture and the seven org-wide counts travel as attribute contributions on nodes sf-orgviz owns.
  • The seven anatomy bands are a view spec, proven to reproduce exactly the band membership, emptiness, notes and caveats that buildBands produces from the same artifact.
  • Every declined integration edge is counted into coverage.unavailable with a scope, reason and detail, instead of being silently dropped.

Fixed

  • Anatomy fragment node ids no longer collide. ssoConfig and site ids were built from issuer and name, which are neither unique nor guaranteed present; a collision makes mergeGraphs return a null graph for the entire merge.
  • Integration edges resolve to a target that exists. The fragment targeted namedCredential.<endpoint>, but named credentials are written as ncred.<DeveloperName> and the endpoint is frequently a URL, so every such edge failed to resolve on every real run.
  • intel map's fragment derived its known-object set from merged coupling edges rather than the sobject catalog, which dropped touches edges and knocked Apex analysis off its SymbolTable branch onto the regex fallback.
  • couples edges now carry source: 'derived' with a named rule. They are pairwise co-reference inferences plus a direction heuristic, not facts read off a SymbolTable.

Deprecated

coupling-graph.json, landscape-manifest.json and anatomy.json are deprecated. They keep their shapes and their byte-for-byte guarantee for the whole 0.x line. 1.0 retires them in favour of the fragments, which carry the same facts in a schema shared with sf-orgviz. Move consumers across during 0.x.

Full detail in CHANGELOG.md.

v0.2.0: sf intel anatomy and View A

Choose a tag to compare

@cclabsnz cclabsnz released this 25 Aug 07:34

Added

  • sf intel anatomy — maps the org one level above coupling: which products live in it, who
    uses it on what licence, what it integrates with, and how people authenticate. Every integration
    edge records how it was detected and, separately, how it was attributed to a product, so a
    confirmed call with an unknown owner is reported as exactly that. Emits anatomy.json. (#7, #8)
  • View A, behind --html — a seven-band layer map answering "what is in this org" in one
    screen, rendered as inline SVG in the existing report shell. Adds no org reads: it renders
    anatomy.json and nothing else. Also adds --branding and --prepared-for, mirroring
    intel map. (#10)
  • coverage.unavailable — the structured counterpart to coverage.notes. Every collector
    that defers a read or has one refused records a stable scope key, a reason of deferred or
    failed, and the human detail. View A classifies bands and tiles from that data and never from
    note prose, so rewording a sentence can no longer change what the picture claims. (#10)

Changed

  • capabilities.changeDataCapture now means enabled, not supported, and the artifact moves to
    version: 2. It previously counted every ChangeEvent sObject the platform exposes, which is a
    property of Salesforce rather than of the org: 419 on an org with CDC switched off entirely, and
    View A drew it as the largest tile in the Ops band. It now reads
    PlatformEventChannelMember.SelectedEntity, covering the standard ChangeEvents channel and
    custom channels alike. The version bumped because the key kept its name while the number behind
    it changed by two orders of magnitude. (#12)
  • A populated band now declares what it did not gather. Previously a band with tiles was
    classified populated and stopped consulting coverage.unavailable, so ten Site channels drew
    as a complete channel inventory while three of the four channel types had never been attempted.
    Such a band now renders "Partly collected" with the reason. (#10)

Fixed

  • The report viewer payload can no longer close its own <script> element. It was embedded as
    raw JSON.stringify output, which escapes neither < nor /, so a value containing
    </script> would end the element early and hand the remainder to the HTML parser as markup.
    Not reachable in practice, since every payload field is a Salesforce API name, but the reports
    are written to be sent to clients. (#15)
  • Coverage rows each carry their own confidence label instead of sharing one. (#4)
  • edges.apexBodies no longer marks the integration and external bands not-collected when only an
    unrelated namespaced-class count fails. (#10)

Security

  • The org-data guard now scans a pull request's own title and body, not just the repository
    and its commit messages. A pull request body is a public page the moment it is opened, and it
    never goes through review first. (#11)
  • js-yaml override raised past the vulnerable range (GHSA-5p4m-2wfm-xmqj). The override
    permitted the patched version without requiring it, so the lockfile stayed on the vulnerable
    one. (#13)
  • SECURITY.md rewritten. It was sf-audit's, copied verbatim, and named the wrong package
    throughout. It also no longer overstates provenance: 0.1.0 carries no attestation. (#15)

This is the first release published through npm trusted publishing (OIDC), so it is the first to carry a build provenance attestation and a CycloneDX SBOM. 0.1.0 was hand-published and carries neither.